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

Text File | 1991-10-06 | 154.2 KB | 4,871 lines

Name  : GetAttrF
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 by 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.

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

   GetAttrF Attr%

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

Name  : GetAttrFx%
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 by 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.

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

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

   Attr% = GetAttrFx%(Buffer$)

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

Name  : GetColor
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
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.

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
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
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
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%
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
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
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 the clock has stopped

Name  : GetDateF
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$
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&

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

   FileDate$ = GetDateFx$(Buffer$)

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

Name  : GetDOSV
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$
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
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
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 DESQview is not loaded)
MinorV%   minor part of the DESQview version

Name  : GetEGA
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 such adapters.

See also GetCRT, GetHGA and GetVGA.

See also GetEGA2, the FUNCTION version of this routine.

   GetEGA Display%, KBytes%

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

Name  : GetEGA2%
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
Class : Miscellaneous
Level : Clone

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 / error level returned by the SHELLed-to program (0-255)

Name  : GetExecPath
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 spec for current program.  Init to at least 80 chars.
SelfLen%    length of the full path spec.

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

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

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

   GetExtM KBytes%

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

Name  : GetFAttr
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.

   GetFAttr FileName$, Attr%

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

Name  : GetFDate
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  : GetFTime
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%
Class : Display / Equipment
Level : Clone

This routine tells you whether a Hercules mono adapter is in use.

Although this routine is documented in the ProBas manual, it does not
actually exist in ProBas 4.x.

See also GetCRT2, GetEGA and GetVGA2.

   IsHGA% = GetHGA%

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

Name  : GetKbd
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
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
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
Class : Input
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%, LeftButton%, RightButton%

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

Name  : GetKey3
Class : Input
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%, LeftButton%, MidBttn%, RightButton%

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

Name  : GetLabel
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 the specified drive.  Init to at least 11 chars.
LabelLen%  length of the volume label
ErrCode%   error code: 0 if no error, else DOS Error

Name  : GetLabel2$
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
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
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
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
Class : Display
Level : Any

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

GetLine differs from the ProBas routine of the same name in that you can use
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 the specified row (init to width of saved screen)
SLen       logical length of text

Name  : GetMouseLoc
Class : Input (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  : GetMoveBack
Class : Disk
Level : DOS

This routine no longer has a purpose.  It is included for compatibility with
the ProBas ToolKit.  Its only effect is to close the file opened by
FindPatch.

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

   GetMoveBack MoveBack%

MoveBack%    unused

Name  : GetNameA
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 at least 12 characters, preferably 80)
NameLen%    length of file name

Name  : GetNameF
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$
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&

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

   FileName$ = GetNameFx$(Buffer$)

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

Name  : GetRows
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%
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
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%(), TopRow%, LeftCol%, BotRow%, RightCol%, Page%, Fast%

TopRow%    top row of the desired screen area
LeftCol%   left column of the desired screen area
BotRow%    bottom row of the desired screen area
RightCol%  right column of the desired screen area
Page%      page from which to get the display area
Fast%      whether to use fast mode (nonzero if so; else slow, for some CGAs)
-------
Array%()   stored image of the selected area of the screen

Name  : GetSerial$
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 number from ("" for current drive)
-------
SerialNr$    serial number of the specified drive

Name  : GetSizeAL
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  : GetSizeF
Class : Disk
Level : DOS

This is an obsolete routine included only for compatibility with the ProBas
library .  See GetSizeFL.

Name  : GetSizeFL
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&
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&

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

   FileSize& = GetSizeFx&(Buffer$)

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

Name  : GetStoreA
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
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.  Initialize to at least 64 chars.
SubLen%    length of the subdirectory name

Name  : GetSub1
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 for which to obtain the default subdirectory
-------
SubDir$    name of the current subdirectory.  Initialize to at least 65 chars.
SubLen%    length of the subdirectory name
ErrCode%   error code: 0 if no error, else DOS Error

Name  : GetSub2$
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.

Note that this routine differs from the ProBas routine by the same name in
that it takes a drive letter parameter.  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 for which to obtain the default subdirectory
-------
SubDir$    name of the current subdirectory.  Initialize to at least 65 chars.

Name  : GetSwitch
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.  Initialize to one character.

Name  : GetSwitch2$
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
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
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
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 the clock has stopped

Name  : GetTimeF
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$
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&

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

   FileTime$ = GetTimeFx$(Buffer$)

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

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

Name  : GetTVScreen
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
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.  If a letter, it will be capitalized.

Name  : GetVerify
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
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%
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
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
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
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
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
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
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
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 differs from the ProBas routine of the same name in that it is a
tad slower, but will work in any graphics mode rather than just CGA modes.

   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
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).

The Fast% parameter is left over from ProBas days and no longer has any
significance.

   GrafRest DSeg%, DOfs%, Fast%

DSeg%      segment of storage array, returned by VARSEG
DOfs%      offset  of storage array, returned by VARPTR
Fast%      meaningless (use any integer value)

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

The Fast% parameter is left over from ProBas days and no longer has any
significance.

   GrafSave DSeg%, DOfs%, Fast%

DSeg%      segment of storage array, returned by VARSEG
DOfs%      offset  of storage array, returned by VARPTR
Fast%      meaningless (use any integer value)

Name  : GXQPrint
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
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
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
Class : Display
Level : Clone

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

Note that the Page% parameter is ignored, at the moment.  Only page 0 is
supported.

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

   HCls Colour%, Page%

Colour%    color (0-1)
Page%      page (0-1; currently ignored)

Name  : HInit
Class : Display
Level : Clone

This routine initializes a Hercules adapter so it can be placed into graphics
mode.  It should be used before HMode.

At the moment, HInit has no effect, but you should use it anyway-- it will be
supported in a later release of PBClone.

The intended purpose of this routine is to specify the maximum graphics page
available.  You can always have page zero.  Page one may be used ONLY if
there is no CGA installed on the same computer.  Note that an EGA or VGA
counts as a CGA if there is any possibility of it being used in CGA mode
while you are using Hercules graphics routines.

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

   HInit MaxPage%

MaxPage%      maximum page (0-1; currently ignored; SEE ABOVE)

Name  : HLine
Class : Display
Level : Clone

This routine draws a line on a Hercules graphics screen.

Note that the Page% parameter is ignored, at the moment.  Only page 0 is
supported.

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

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

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)
Page%      page (0-1; currently ignored)

Name  : HMode
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.

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

   HMode Graphics%

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

Name  : HPage
Class : Display
Level : Clone

This routine sets the active display page for a Hercules graphics screen.
The pages available depends on what you specified for HInit.

Note that the Page% parameter is ignored, at the moment.  Only page 0 is
supported.

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

   HPage Page%

Page%      page (0-1; currently ignored)

Name  : HPrint
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.

Note that the Page% parameter is ignored, at the moment.  Only page 0 is
supported.

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

   HPrint St$, Row%, Column%, Page%

St$        text to display
Row%       row (1-43)
Column%    column (1-90)
Page%      page (0-1; currently ignored)

Name  : HSetPixel
Class : Display
Level : Clone

This routine draws a dot on a Hercules graphics screen.

Note that the Page% parameter is ignored, at the moment.  Only page 0 is
supported.

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

   HSetPixel X%, Y%, Colour%, Page%

X%         graphics column (0-719)
Y%         graphics row (0-347)
Colour%    color (0-1)
Page%      page (0-1; currently ignored)

Name  : HTestPixel
Class : Display
Level : Clone

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

Note that the Page% parameter is ignored, at the moment.  Only page 0 is
supported.

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

   HTestPixel X%, Y%, Colour%, Page%

X%         graphics column (0-719)
Y%         graphics row (0-347)
Page%      page (0-1; currently ignored)
-------
Colour%    color (0-1)

Name  : IdentifyFile
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  : InsChr
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
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  : IntVector
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
earlier DOS versions did not always have the sense to initialize unused
vectors that way.

Frankly, I can't see much use for this routine, but it's in ProBas, so...

   IntVector DSeg%, DOfs%, Interrupt%

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

Name  : Int2Date
Class : Time
Level : Any

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

   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 year handling)

Name  : Int2Time
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.

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

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

Name  : IStr$
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  : IVal%
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
Class : Input / Equipment
Level : Clone

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

KbdType differs from the ProBas routine of the same name in that it has
additional error checking.  If it 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%
Class : Input / Equipment
Level : Clone

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

KbdType2% differs from the ProBas routine of the same name in that it has
additional error checking.  If it 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
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&
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 (0 if no valid number)

Name  : Locase
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
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  : LClose
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
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
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
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
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
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&
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
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
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%
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#
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&
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!
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
Class : Numeric
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, else an overflow or (First% > Last%)

Name  : MeanAverageI
Class : Numeric
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, else an overflow or (First% > Last%)

Name  : MeanAverageL
Class : Numeric
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, else an overflow or (First% > Last%)

Name  : MeanAverageS
Class : Numeric
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 there was no error, else an overflow or (First% > Last%)

Name  : MemSwap
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%
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#
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&
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!
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
Class : Input (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
Class : Input (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
Class : Input (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
Class : Input (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%     number of times the left button has been pressed since last check
RightB%    number of times the right button has been pressed since last check

Name  : MMClick3
Class : Input (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%     number of times the left button has been pressed since last check
MiddleB%   number of times the middle button has been pressed since last check
RightB%    number of times the right button has been pressed since last check

Name  : MMCursorOff
Class : Input (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
Class : Input (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
Class : Input (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
Class : Input (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
Class : Input (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
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
Class : Input (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  : MousePen
Class : Input (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 to have the mouse emulate a light pen (0 if no)

Name  : MouseRest
Class : Input (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
Class : Input (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 to the length specified by MouseBuffer.

Name  : MulMatI
Class : Numeric
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.  It can also be
used to subtract (just specify a negative value).  If there was a numeric
overflow at any point in the operation, an error code will be returned.

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

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

Name  : MultiAND
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
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
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
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$
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  : NumFormat
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
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%
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
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.

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.

This routine does not exist in ProBas.

   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  : ParseFSpec
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
DLen%       length of Drive$
SubDir$     subdirectory
SLen%       length of Subdir$
File$       file name
FLen%       length of File$

Name  : PatchDone
Class : Disk
Level : DOS

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

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

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

   PatchDone

Name  : PCDat$
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
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 at least 8 chars.

Name  : PCType
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%
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  : PrintFile
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.

The PrintFile routine differs from its ProBas equivalent in that it returns
normal DOS error codes rather than using artificial printer error codes.

   PrintFile FileName$, ErrCode%

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

Name  : PrintScreen
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
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.

The ProBas version of this routine can't recognize a NEC processor.

   Processor ProcType%

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

Name  : Processor2%
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.

The ProBas version of this routine can't recognize a NEC processor.

   ProcType% = Processor2%

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

Name  : PrtSc
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
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  : PutScreen
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%(), TopRow%, LeftCol%, BotRow%, RightCol%, Page%, Fast%

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

Name  : QPrint
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 (nonzero if so; else slow, for some CGAs)

Name  : Rand%
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.

The Rand% function does not exist in ProBas.

   Number% = Rand%(Range%)

Range%      range of desired pseudo-random number
-------
Number%     pseudo-random number from 0 to Range% - 1

Name  : ReadBitF
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.

This routine differs from its ProBas equivalent in that the ElementNr
parameter is a LONG instead of an INTEGER.  This allows you to access up to
32K bytes at a time, even if each element is composed of a single bit.

   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
Class : Miscellaneous
Level : Clone

This routine restarts the computer, just like typing Control-Alt-Del at the
keyboard.

   Reboot

Name  : 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
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 TopRow%, LeftCol%, BottomRow%, RightCol%, Attr%, Page%, Fast%

TopRow%     top row of area to recolor
LeftCol%    left column of area to recolor
BottomRow%  bottom row of area to recolor
RightCol%   right column of area to recolor
Attr%       desired color
Page%       display page (normally zero)
Fast%       whether to use fast mode (0 if no, to avoid snow on CGAs)

Name  : RedirectIn%
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%
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
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
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
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
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.

Note that the PBClone implementation differs from the ProBas version in the
matter of error codes.  ProBas returns any of three error codes, none of
which makes much sense: 1, the search string wasn't found (but we return that
information in another variable); 2, the main string is null (so what?); 3,
the replacement string is the same as the search string (again, so what?).
Somehow, ProBas misses the one true error, which is the only error returned
by PBClone: -1, the search string was 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
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%     number of times to retry if a file-sharing violation occurs
WaitTime%  amount of time to delay between retries

Name  : 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  : RInstr
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 (or 0 if no match)

Name  : RRotate
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
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
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 (ASCII), 2 extended (scan code)
CharCode%   key ASCII or scan code

Name  : 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
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 (nonzero if so; may cause snow on CGAs)

Name  : ScrSave
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 (nonzero if so; may cause snow on CGAs)
-------
Array%()   saved display information

Name  : Scrunch
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 the array in which to store the compressed image
COfs%     offset of the array in which to store the compressed image
-------
Bytes%    number of bytes in the compressed image

Name  : Sec2Time$
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
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
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
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!

This routine offers a wider variety of parity and word length settings than
the routine of the same name in ProBas.

   SetComm CommPort%, Bps%, Parity%, WordLength%, StopBits%

CommPort%    serial port number (1-4, although 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" actually means 1 1/2)

Name  : SetCommAddr
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
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 year handling)

Name  : SetDrv
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
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
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 utilities-- leave alone)

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
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 FileName$, MonthNr%, Day%, Year%, Hour%, Minute%, Second%

FileName$    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 year handling)
Hour%        hour (0-23)
Minute%      minute (0-59)
Second%      second (0-59; if odd, will be rounded down to an even number)
-------
MonthNr%     -1 if there was an error, else unchanged

Name  : SetKbd
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 if no)
Scrl%      whether to turn on "scroll lock" (0 if no)

Name  : SetLabel
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
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, obtained by VARSEG
DOfs%      offset of the first array element to add, obtained by VARPTR
Elements%  number of array elements to which to add
Value%     value to which to set each array element

Name  : SetMatL
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, obtained by VARSEG
DOfs%      offset of the first array element to add, obtained by VARPTR
Elements%  number of array elements to which to add
Value&     value to which to set each array element

Name  : SetMouseLoc
Class : Input (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
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$))

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

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

   SetPatch St$

St$       string to patch into the current DATA statement

Name  : SetRows
Class : Display
Level : BIOS

This routine sets the number of rows on the display.  This is normally 25,
but can be changed to 43 on EGA and VGA displays, or 50 on VGA displays.
This can be done in the current versions of BASIC with the WIDTH statement.
The SetRows routine is only included in PBClone for compatibility with ProBas.

   SetRows Rows%

Rows%    desired number of text rows on the display

Name  : SetSub
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
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
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
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
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 the number of chars desired.
BytesRead%  number of bytes actually read from the file (if error)
ErrCode%    error code: 0 if no error, else DOS Error

Name  : SFWrite
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 actually written to the file (if error)
ErrCode%    error code: 0 if no error, else DOS Error

Name  : ShiftL
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
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
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
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  : SInput
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.

Routines in this series include:
   SInput, SInputSet, SInputSet1, SInputSet2

Since everyone has their own ideas about the perfect input routine, I have
coded 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 desired input (may contain default entry)
SLen%       length of default entry (0 if none)
Valid%      valid character types (see above)
MustFill%   whether the 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 (normally 13 for <CR> or 27 for <ESC>)

Name  : SInputSet
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%    whether extended keys can be used to exit SInput (default 0, no)
BadBeep%    whether to beep on invalid keys (default 0, no)
FullBeep%   whether to beep when input field is full (default 0, no)
Fast%       whether to use fast displays that may make CGAs flicker (def 0, no)

Name  : SInputSet1
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 position within the input field (default 0)
FullExit%   whether to exit automatically when input is full (default 0, no)

Name  : SInputSet2
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 the tab key can be used to exit (default 0, no)

Name  : Soundex
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 at least the length of the original string.
CodeLen%  length of the result code

Name  : SpeedKey
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.

   SpeedKey RepDelay%, RepRate%

RepDelay%   delay before starting to repeat a key (0-3, default 1)
RepRate%    rate at which to repeat key (0-31, default 11)

Name  : Split
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.

This version of Split differs from the ProBas version in that it can handle
text screens of any size: 40x25, 80x25, 80x43, etc.

   Split

Name  : 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
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
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
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
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
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
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
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
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$
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
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.

Note that this routine is not compatible with the ProBas routine of the same
name.  The algorithm is identical but the 2-gram list differs.

   StrSquLen2 St$, ResultLen%
   Result$ = SPACE$(ResultLen%)
   StrSqu2 St$, Result$

St$       string to compress
-------
Result$   compressed string

Name  : StrSquLen2
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.

Note that this routine is not compatible with the ProBas routine of the same
name.  The algorithm is identical but the 2-gram list differs.

   StrSquLen2 St$, ResultLen%
   Result$ = SPACE$(ResultLen%)
   StrSqu2 St$, Result$

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

Name  : StrUnsqu2
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.

Note that this routine is not compatible with the ProBas routine of the same
name.  The algorithm is identical but the 2-gram list differs.

   StrUnsquLen2 St$, ResultLen%
   Result$ = SPACE$(ResultLen%)
   StrUnsqu2 St$, Result$

St$       string to decompress
-------
Result$   decompressed string

Name  : StrUnsquLen2
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.

Note that this routine is not compatible with the ProBas routine of the same
name.  The algorithm is identical but the 2-gram list differs.

   StrUnsquLen2 St$, ResultLen%
   Result$ = SPACE$(ResultLen%)
   StrUnsqu2 St$, Result$

St$          string to decompress
-------
ResultLen%   length of the decompressed string

Name  : SubExist
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%
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.

The ProBas library does not have this function.

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
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&
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
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".

This routine differs from the ProBas routine by the same name in that you can
get the current time in the desired format by passing zeroes for Hour%,
Minute% and Second%.

   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
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
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%       where the first char of the desired type was found (or 0)

Name  : TypeIn
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 PBClone version of TypeIn,
unlike the ProBas version, 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
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.

This routine does not exist in ProBas.

   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 characters (milliseconds; 20-60 is reasonable)
TmpAttr%   color/attribute for just-displayed character
Attr%      color/attribute for character after the delay is up
Fast%      whether to use fast displays (may cause snow on CGAs) (0 no)

Name  : UnCalcAttr
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
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 the array in which to store the expanded image
DOfs%     offset of the array in which to store the expanded image
CSeg%     segment of the compressed image
COfs%     offset of the compressed image

Name  : UnSplit
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 25x80 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 if no, to avoid snow on CGAs)

Name  : Upcase
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
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
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
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
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
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
Class : Time
Level : Any

This routine tells you the day of the week for any given date.

WeekDay1 works like the routine by the same name in the ProBas ToolKit.

   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  : WindowManager
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 a specified delay in milliseconds (15 works well for me)

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

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

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

Name  : WindowMan2
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 TopRow%, LeftCol%, BottomRow%, RightCol%, Frame%, FSt$,
      Fore%, Back%, Grow%, Shade%, TFore%, Title$, Page%, Fast%

TopRow%     top row of window
LeftCol%    left column of window
BottomRow%  bottom row of window
RightCol%   right column of window
Frame%      frame type (see above)
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 if no, to avoid snow on CGAs)

Name  : WindowMan3
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 if no, to avoid snow on CGAs)
Title$      window title ("" if none)

Name  : WindowMan4
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 TopRow%, LeftCol%, BottomRow%, RightCol%, Frame%, Attr%,
      Page%, Fast%

TopRow%     top row of window
LeftCol%    left column of window
BottomRow%  bottom row of window
RightCol%   right column of window
Frame%      frame type (see above)
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
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.

This routine differs from its ProBas equivalent in that the ElementNr
parameter is a LONG instead of an INTEGER.  This allows you to access up to
32K bytes at a time, even if each element is composed of a single bit.

   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 (0-255 or less, depending on BitLen%)

Name  : Xlate
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
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  : XQPrint
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 displays; normally zero)
Fast%     whether to use fast mode (nonzero if so; may cause snow on CGAs)