Black Box 4/BlackBox.cdr/progbas/dframe31.arj/PBC-SUBS.DOC

Text File | 1992-02-17 | 23.2 KB | 737 lines

 The following routines are available for your use. DoorFrame itself does not
use most of the routines so you may retain or delete them from DFRAME.LIB as
you see fit (the ones DoorFrame uses are noted - DON'T DELETE THEM!). The
library is modularized so if you don't CALL a routine in your code, it will
not be included in the final .EXE file. Since these routines come from the
PBClone library by Tom Hanlin, I have taken the liberty of including his
descriptions of the routines.


Name  : BIOSInkey
Class : Input
Level : BIOS

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

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

   BIOSInkey AscCode%, ScanCode%

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

Name  : CalcAttr                (Called by DoorFrame - DON'T DELETE!)
Class : Display
Level : Any

An attribute is a combination of the foreground and background colors in a
format which is used by all types of displays when in text mode.

Foreground colors are usually specified as 0-15, with backgrounds as 0-7.

   CalcAttr Foreground%, Background%, Attr%

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


Name  : CDROM
Class : Disk / Equipment
Level : DOS

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

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

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

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


Name  : CheckShare2%         (Check for SHARE)
Class : Disk
Level : DOS

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

   ShareActive% = CheckShare2%

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


Name  : DelFile                 (Called by DoorFrame - DON'T DELETE!)
Class : Disk
Level : DOS

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

   DelFile FileName$, ErrCode%

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


Name  : DriveSpace&
Class : Disk
Level : DOS

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

   BytesFree& = DriveSpace&(Drive$)

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


Name  : EMSBuffer
Class : Memory
Level : BIOS

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

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

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


Name  : EMSClose
Class : Memory
Level : BIOS

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

   EMSClose ArrayHandle%

ArrayHandle%    handle of an EMS array


Name  : EMSGet
Class : Memory
Level : BIOS

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

   EMSGet ArrayHandle%, ElementNr&, Value

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


Name  : EMSOpen
Class : Memory
Level : BIOS

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

    1   INTEGER
    2   LONG or SINGLE
    3   DOUBLE

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

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

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

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


Name  : EMSPut
Class : Memory
Level : BIOS

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

   EMSPut ArrayHandle%, ElementNr&, Value

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


Name  : EMSRest
Class : Memory
Level : BIOS

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

   EMSRest EMSState$

EMSState$    saved EMS array state


Name  : EMSSave
Class : Memory
Level : BIOS

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

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

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


Name  : EnhKbd
Class : Input
Level : BIOS

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

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

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

   EnhKbd Enable%

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


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

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

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

   Get4DOSv MajorV%, MinorV%

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


Name  : GetDOSV                 (Called by DoorFrame - DON'T DELETE!)
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  : 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  : 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  : 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  : GetTView             (Get TopView)
Class : Miscellaneous
Level : BIOS

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

See also GetDView, GetTVScreen, UpdTVScreen.

   GetTView Installed%

-------
Installed%   whether a TopView-type multitasker is loaded (0 no)


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

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

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

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

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

See also GetDView, GetTView, UpdTVScreen.

   GetTVScreen DSeg%, DOfs%

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


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

   LRotate St$

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


Name  : NameCase                (Called by DoorFrame - DON'T DELETE!)
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  : 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  : 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  : 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  : 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  : UpdTVScreen          (Update TopView Screen)
Class : Display
Level : BIOS

UpdTVScreen tells a TopView-compatible multitasker to update the screen using
a specified screen buffer (use GetTVScreen to get the buffer location).  Some
multitaskers will do this automatically, but some won't.  It's safe to use
this routine either way.

See also GetDView, GetTView, GetTVScreen.

   UpdTVScreen DSeg%, DOfs%

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


Name  : WinCheck             (Windows Check)
Class : Equipment
Level : BIOS

The WinCheck routine tells you what version of Microsoft Windows is in use,
if any.  It returns the results as two integers containing the major and
minor version numbers.  For instance, Windows 3.0 would return a major number
of 3, minor 0.  Windows/386 v2.x will be identified as 2.0.  If Windows is
not running, 0.0 will be returned.  NOTE that this routine is not able to
detect Windows 1.x versions!

   WinCheck MajorV%, MinorV%

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