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

Text File | 1991-10-09 | 46.8 KB | 932 lines

                             The PBClone Library
                           =---------------------=
                                 Version 1.6

              PBCLONE  Copyright (c) 1990-1991  Thomas G. Hanlin III



This library is too large for the QB/QBX compilers to cope with as a unit.
The Library Wizard utility (available separately as LIBWIZxx.ZIP) allows you
to create custom libraries containing just the routines you need.

This is PBClone, a library of assembly language and BASIC routines for use
with QuickBASIC version 4.5.  Full support for other recent compilers is
provided with registration (QB 4.0-4.5, BC 6.0-7.1).  The PBClone collection
is copyrighted and may be distributed only under the following conditions:

   1) No fee of over $10.00 may be charged for distribution.  This
      restriction applies only to physical copies and is not meant to
      prevent distribution by telecommunication services.

   2) All PBClone files must be distributed together in original, unaltered
      form.  See FILES.LST for a list of the 24 files currently included.

   3) No files may be added to the PBClone collection.  This applies most
      specifically to the practice of adding BBS ads to archives, which I
      find seriously offensive.

You use this library at your own risk.  It has been tested by me on my own
computer, but I will not assume any responsibility for any problems which
PBClone may cause you.  If you do encounter a problem, please let me know
about it, and I will do my best to verify and repair the error.

It is expected that if you find PBClone useful, you will register your copy.
You may not use PBClone routines in programs intended for sale unless you
have registered.  Registration entitles you to receive the latest version of
PBClone, complete with full source code in assembly language and BASIC.  The
assembly code is designed for the MASM 6.0 assembler and may require minor
modifications if you wish to use it with OPTASM, TASM, or earlier versions of
MASM.  You will be able to compile the BASIC code with whatever version of
the compiler you have, allowing you to use PBClone with QuickBASIC versions
4.0 - 4.5 and BASCOM versions 6.0 - 7.1.  Note that Microsoft's "far strings"
are only supported if you recompile, so if you need 'em... register!

New files have been added to help registered owners convert the source code
to new libraries (for use with compilers other than QB 4.5, for instance).
These are ASMCOMP.BAT and BASCOMP.BAT, which reassemble/recompile the
sources, and LIBMAKE.IN, which can be used with LIB to recreate the entire
library:
   LIB @LIBMAKE.IN

For information on the long and strange history on PBClone, read the
following section, entitled "History".

                            The History of PBClone



In the year 1984, or thereabouts, I created The Advanced Function Library for
BASIC (ADVBAS).  It was originally designed for my own use, to enhance the
limited capabilities of IBM BASCOM 1.0.  Since I found the routines very
useful and there weren't any other BASIC libraries available, I decided to
put ADVBAS out as a shareware project.  This was a moderate success and I
continued to update ADVBAS on a regular basis for several years.

In 1987, the utility of ADVBAS caught the eye of the president of a small
company for which I was doing a bit of programming.  We came to an agreement,
and shortly thereafter Hammerly Computer Services, Inc, was doing a very good
business indeed on the commercial version of ADVBAS and related products:
ProBas, the ProBas ToolKit, the ProBas TeleComm ToolKit, etc, etc.  As part
of this agreement, the original ADVBAS library was "frozen" and couldn't be
updated without permission from HCSI.  They let me update it on occasion,
however, considering it good advertising for ProBas; and ProBas-related sales
were booming, so on the whole I was delighted.

Unfortunately, as mentioned in previous versions of PBClone, I've had some
serious problems with HCSI since then insofar as regards payment.  I have
since settled the particular problems mentioned.  However, HCSI has currently
fallen victim to a rather bizarre set of circumstances, and it appears that I
am once again owed a large sum of money which I may never be paid.  Sigh.
Well, as they say... "Fool me once, shame on you.  Fool me twice, shame on
me."  Mea culpa.

Since (this time) it isn't entirely their fault, I'm going to go in a new
direction with PBClone.  Instead of using ProBas as a model, I'll be adding
new routines that I'd like to see.  Within a year or so, the two libraries
should have diverged significantly, hopefully to the benefit of PBClone
<grin>.  Let's face it, PBClone differs quite a bit from ProBas anyway-- I
could never resist the urge to improve on the old design!  With this
transition, I'll have added freedom to improve the library without being
stuck with ideas that may have seemed good to me in 1987.

In the meantime, let me note what a bargain PBClone continues to be!  For a
mere $25 registration, it contains 2/3 the routines in ProBas 4.0 ($175) and
an assortment of routines from the ProBas ToolKit 2.0 ($99).  Registration
gets you full source code, which isn't available for ProBas or the ToolKit at
any price.  You won't find a better bargain anywhere!  Do us both a favor and
register now!  See the REGISTER.TXT file for the intimate details.

If you feel you can't do without printed manuals and phone technical support,
I'd like to recommend Crescent Software.  They provide excellent support and
have decent products.  Of course, you will have to pay commercial prices
(which, you may have noticed, are going up steadily)!

                            The TSR File Viewer



Since there are hundreds of routines in PBClone, it isn't always exactly easy
to remember which routine you want or how to use it.  This is a particular
problem when you're in the middle of writing a program.  So, I've written a
TSR file viewer... it's crude, but it gets the job done.

Just type "FV" to install the TSR.  Alt-V activates it.  "FV /D" removes it
from memory.

!!! ----== NOTE ==---- !!!
Please check FV with a nonessential application first!  It appears to work
fine in the QuickBASIC environment, but it locks up my favorite editor, so I
can't guarantee that it will behave properly in all circumstances.

First, FV will ask you for the file to view.  This may contain drive and
subdirectory information as well as the file name.  Second, you will be asked
for a search string.  If you enter a search string, viewing will start at the
part of the file that contains that search string.  If you just press enter,
viewing will start at the beginning of the file.  The file will be presented
to you one page at a time.  I suggest viewing PBCLONE.INF or PBCLONE.MAN.

FV was written in BASIC using Crescent's PDQ library, with the "simplified"
TSR handler (which doesn't seem to have been entirely debugged).  Then again,
TSRs are a tricky matter, especially with BASIC...

                                General Notes



The initial version of PBClone had only one manual.  However, since there are
so many routines, I've split the manual into a general documentation file and
a reference manual.  You won't want to print the PBCLONE.MAN file unless you
have a lot of time and printer paper!  In contrast, this file (PBCLONE.DOC)
has been kept small to allow ready printing.  It contains general notes,
cross-reference listings of the routines, and assorted charts.

On the whole, the routines in this library are directly compatible with those
in ProBas.  Some changes have been made, however-- many routines are faster,
some slower, and some (like the BSq, BUsq, and BUsqLen routines) don't
produce quite the same results on the same data.  Some routines which were
specific to particular versions of BASIC in ProBas will work with any version
in PBClone.  Many ProBas routines haven't been implemented in PBClone yet.
Almost all PBClone routines require the inclusion of a declaration file in
your program, whereas ProBas (designed before the DECLARE statement) rarely
needs such a thing.  So, if you're converting from ProBas to PBClone, keep
these things in mind.

When a PBClone returns a Boolean (on or off) value, it will always be 0 if
off, -1 if on; this is unlike ProBas, which would often return any non-zero
value for an "on" state.  Booleans passed to PBClone may still use any
non-zero value to indicate a "true" or "on" condition, however.

Critical error handling has been incorporated into all disk and device
routines.  You will never have to worry about "R>etry, A>bort, I>gnore"
again, so long as you use PBClone for your disk and device management.

PBClone file handling is very flexible but may be confusing to people used to
BASIC's strongly-moded files.  PBClone file handling is most similar to BASIC
files opened in BINARY mode.  You may read or write any amount of information
at a time.  After each read or write takes place, the file pointer is updated
appropriately, so you can use sequential access techniques without further
effort.  Random access is also possible, using FSetLoc/FSetOfs/FSetRec to set
the file pointer position.  Those of you who are familiar with C or Pascal
file handling will notice strong similarities in this approach, which is
based on techniques that have long been standard in the industry.

Many routines are available both as SUBprograms and as FUNCTIONs.  The former
is for compatibility with older programs which were designed before BASIC was
capable of using FUNCTIONs.  You may use either, of course, although the
FUNCTION version of a routine is often more convenient.

                                General Notes



The PBClone library can be used in conjunction with other libraries.  If
there is a conflict in routine names between the two libraries, the OBJTOOL
utility can be used to rename one or the other routine.  Due to the large
size of PBClone, you will probably need to select just the routines you need,
rather than combining the entire libraries, in order to avoid overflowing
LINK limitations.  OBJTOOL can help you find out which routines are in what
modules.  The LIB utility can be used to alter existing libraries, or you can
build your own custom libraries from the ground up, using LIBWIZ.  See the
LIBRARY.TXT file if you are not familiar with libraries.

OBJTOOL is included on the sampler disk that comes with the registered
version of PBClone.  It may also be available at your local BBS.

Of the routines in ProBas which are not (yet) included in PBClone, the most
notable are the more advanced graphics routines.  These will be included at a
later time.

A number of PBClone routines are more flexible than the corresponding ProBas
routines, such as SetComm (more Parity and WordLength options).  These give
you more choices without interfering with compatibility.

If you have not used ADVBAS, ProBas, or PBClone before, you may be unfamiliar
with the array handling conventions used here.  In almost all array routines,
you will see a pair of parameters (e.g. DSeg% and DOfs%) used to represent an
array.  These values are obtained by the BASIC functions VARSEG and VARPTR:

   DSeg% = VARSEG(Array(1))    ' or whatever the first desired element may be
   DOfs% = VARPTR(Array(1))

This is the way that current versions of QuickBASIC and BASCOM pass arrays,
TYPEd values, and fixed-length STRING values to assembly-language routines.
It tells the routine where in memory to find the value(s).  Since these
values may move around in memory, it is important to get the VARSEG and
VARPTR just before you call the routine.  Any routine that accepts a segment
and an offset can be used with arrays, TYPEd values, and fixed-length strings
interchangeably.  This allows for considerable flexibility.

Virtually all of the variables used in PBClone are integers.  In this manual,
integers are indicated specifically by use of the "%" integer postfix.  The
use of DEFINT A-Z in your program will cause your variables to be integers by
default, which I would recommend unless you use floating point heavily.

                                General Notes



Most of the routines in ProBas did not require a DECLARE if the CALL syntax
was used.  This is not true of PBClone, which requires DECLAREs.  There are
numerous advantages to this:

   1) BASIC can more easily detect any errors in your calling syntax
   2) You may use CALL or the simplified syntax used in this manual
   3) Many of the routines are smaller and faster due to options only
      available when DECLARE is used.

The DECLAREs are generated in a .BI file by LIBWIZ.  Assuming you named the
library PBC, you can include the DECLAREs in your program with this statement:

   REM $INCLUDE: 'PBC.BI'

The PBC.BI file must be in the same directory as your program, or you can put
it into a specific directory by setting an environment variable.  I keep my
include files in a directory called C:\INCLUDE, so I have the following line
in my AUTOEXEC.BAT:

   SET INCLUDE=C:\INCLUDE

As mentioned, there are now two ways of calling any subprogram.  You can use
the CALL keyword or an implicit call.  In the case of the CopyFile routine,
for instance, you could use either of these calls interchangeably:

   CALL CopyFile (FromFile$, ToFile$, ErrCode%)    ' old-style explicit call

   CopyFile FromFile$, ToFile$, ErrCode%           ' new-style implicit call

How you capitalize the names of the variables and routines is up to you.  I
like mixed uppercase and lowercase, but it really doesn't matter.  You can
also change the names of the variables or even replace them with constants,
as long as you maintain the correct type:

   COPYfile "C:\AUTOEXEC.BAT", "A:AUTOEXEC.BAT", errornumber%

One oddity in QuickBASIC is that it can get confused if you have a variable
that has the same name as a subprogram or function.  The routine in PBClone
which is most likely to be affected by this is called Month.  Instead of
calling a month variable Month$ or Month%, use names like MonthName$ and
MonthNr% instead.

                                General Notes



If you have registered PBClone and wish to recompile all of the routines
written in BASIC, first place these routines in their own directory.  Then:

   FOR %x IN (*.BAS) DO BC %x /o;

Of course, you can use whatever switches you like.  I find "/o" sufficient
for my own purposes.  Note that you will need to use "%%x" instead of "%x" if
you place this statement in a batch file.

The same approach works for reassembling with MASM.  Note that if you wish to
create a far string version of PBClone (for QBX or BASCOM 7.x "PDS"), you
should use the switch "/Fs" with BC, or "/DFarString" with MASM.

The DEMO program, as of PBClone v1.5 at least, was linked with both PBClone
and Crescent's PDQ library.  Of course, DEMO does not require PDQ, but using
PDQ makes the resulting .EXE file much smaller.  If you do not have PDQ, you
can create a new DEMO.EXE by running CREATE.BAT.  If you are a PDQ owner, you
may prefer this:

   LINK DEMO/NOD/NOE/EX,,NUL,PBC+PDQ;

If you find any bugs or problems with PBClone, please let me know.  You can
reach me through many BBS network BASIC forums (FIDO, ILINK, RIME...) as well
as through U.S. mail.  Please DO NOT call me directly!

Your suggestions are also most welcome.

                              Routine Reference



Disk:
   BootDrive     determine the drive used to boot the computer
   BootDrive2$   determine the drive used to boot the computer
   CDROM         see if a CD-ROM is installed and get info about it
   CDROM2%       see if a CD-ROM is installed and get info about it
   CheckDisk     see if a disk is ready to be accessed
   CheckDsk%     see if a disk is ready to be accessed
   CheckShare    determine whether SHARE is installed
   CheckShare2%  determine whether SHARE is installed
   CloseA        close an archive opened by FindFirstA
   CopyFile      copy a single file
   DelFile       delete a file
   DelSub        delete a subdirectory
   DFRead        read from a file into an array or other memory area
   DFWrite       write to a file from an array or other memory area
   DiskStat      get information on disk memory
   DrvSpace      see how much space is free on a disk (obsolete)
   DrvSpaceL     see how much space is free on a disk
   DriveSpace&   see how much space is free on a disk
   DrvType       see if a drive is removeable and/or networked
   Exist         see if a file exists
   Exist2%       see if a file exists
   ExtendFSpec   check a file path spec for errors, complete it and format it
   FClose        close a file
   FCreate       create a file and open it for access
   FGetLoc       get the position of a file pointer
   FGetLoc2%     get the position of a file pointer
   FileCopy      copy one or more files
   FileCRC       calculate a 32-bit CRC for a file
   FindFirstA    find the first file in an archive to match your specifications
   FindFirstF    find the first file to match your specifications
   FindFirstFx   find the first file to match your specs (allows recursion)
   FindNextA     find any other files in an archive which match your specs
   FindNextF     find any other files which match your specifications
   FindNextFx    find any other files which match your specs (allows recursion)
   FindPatch     finds where to patch an .EXE for self-modifying files
   Floppies      see how many floppy drives are attached
   Floppies2%    see how many floppy drives are attached
   FlushToDisk   flush a file to disk (force it to be updated)
   FOpen         open a file
   ForceMatch$   force a file to match a specified wildcard pattern
   FSetEnd       move to the end of a file
   FSetLoc       move to a specific location in a file
   FSetOfs       move backwards or forwards within a file
   FSetRec       move to a specific record location in a file
   FSetSize      set the size of a file
   FSize         get the size of a file
   FSize2&       get the size of a file
   GetAttrF      get the attribute of a file matched by FindFirstF/FindNextF
   GetAttrFx%    get the attribute of a file matched by FindFirstFx/FindNextFx
   GetCRCA       get the CRC (16-bit) of a file matched by FindFirstA/FindNextA
   GetCRCAL      get the CRC (32-bit) of a file matched by FindFirstA/FindNextA
   GetDateA      get the date of a file matched by FindFirstA/FindNextA
   GetDateF      get the date of a file matched by FindFirstF/FindNextF
   GetDateF$     get the date of a file matched by FindFirstFx/FindNextFx

                              Routine Reference



Disk:
   GetDrive$     get the default drive
   GetDrv        get the default drive
   GetExecPath   get the drive, subdirectory, and name of the current program
   GetFAttr      get the attribute of a file
   GetFDate      get the date of a file
   GetFTime      get the time of a file
   GetLabel      get a disk volume label
   GetLabel2$    get a disk volume label
   GetMoveBack   no longer used; retained for compatibility purposes
   GetNameA      get the name of a file matched by FindFirstA/FindNextA
   GetNameF      get the name of a file matched by FindFirstF/FindNextF
   GetNameFx$    get the name of a file matched by FindFirstFx/FindNextFx
   GetSerial     get a disk serial number
   GetSizeAL     get the size of a file matched by FindFirstA/FindNextA
   GetSizeF      get the size of a file matched by FindFirstF/FindNextF (obs.)
   GetSizeFL     get the size of a file matched by FindFirstF/FindNextF
   GetSizeFx&    get the size of a file matched by FindFirstFx/FindNextFx
   GetStoreA     get the storage type of a file matched by FindFirstA/FindNextA
   GetSub        get the default subdirectory (obsolete)
   GetSub1       get the default subdirectory on a specified drive
   GetSub2$      get the default subdirectory on a specified drive
   GetTimeA      get the time of a file matched by FindFirstA/FindNextA
   GetTimeF      get the time of a file matched by FindFirstF/FindNextF
   GetTimeFx$    get the time of a file matched by FindFirstFx/FindNextFx
   GetVerify     determine the status of the DOS "verify" setting
   GLoad         load a binary image from a file (like BLOAD)
   IdentifyFile  try to identify a file
   MakeSub       create a subdirectory
   MatchFile     see if a filename matches a filespec with wildcards
   ObjScan       scan an .OBJ file, returning public and external names
   ParseFSpec    split a filespec into drive, subdirectory, and filename
   PatchDone     terminates patching of an .EXE file
   Rename        rename a file
   RenSub        rename a subdirectory
   Retries       set the retries used for file networking
   SetDrv        set the default drive
   SetFAttr      set the attribute of a file
   SetFTD        set the time and date of a file
   SetLabel      set a disk volume label
   SetPatch      installs a patch into an .EXE file
   SetSub        set the default subdirectory
   SetVerify     set the state of the DOS "verify" switch
   SFRead        read from a file into a string
   SFWrite       write from a string into a file
   SubExist      determine whether a subdirectory exists
   SubExist2%    determine whether a subdirectory exists

                              Routine Reference



Display:
   BarMenu       bar menu (single row) for keyboard only
   BarMenuM      bar menu (single row) for keyboard or mouse
   BigPrint      display text in huge letters
   BkSpace       backspace destructively with wrap
   BkScroll      scroll an area of the screen down
   Blink         switch between blinking and intense background colors
   CalcAttr      calculate a color/attribute from foreground and background
   CalcAttr2%    calculate a color/attribute from foreground and background
   CalcSize      calculate the size needed in an array to save a screen area
   CalcVGAColor  calculate a VGA palette color setting
   ClearArea     clear an area of the screen with special effects
   Clock         display a clock on the screen constantly
   ClockSet      set various parameters for the clock
   ClrCols       clear between specified columns on a row
   ClrEOL        clear to the end of the row
   ClrEOP        clear to the end of the screen
   ClrSOL        clear to the start of the row
   ClrSOP        clear to the start of the screen
   CPrintScreen1 send a SCREEN 1 display to the printer
   CPrintScreen2 send a SCREEN 2 display to the printer
   CursorInfo    return cursor visibility, current size, and maximum size
   CWindowManager display a pop-up window on a CGA graphics screen
   DClear        clear a display being kept in an array
   DClearSS      clear a display of an unusual size being kept in an array
   DelChr        delete a character from the screen
   DelLine       delete a row from the screen
   DGClear       clear a CGA virtual screen
   DGetScreen    get an area of the screen into an array
   DGQPrint      write to a CGA virtual screen (SCREEN 1 type)
   DGXQPrint     write to a CGA virtual screen (SCREEN 2 type)
   DGXQPrint1    write to a CGA virtual screen (SCREEN 2 type)
   Dissolve      clear the screen with special effects
   DMPrint       display text directly through DOS services
   DOSClrEol     clears from the cursor to the end of the line using DOS output
   DOSCls        clears the screen using DOS output
   DOSColor      sets the screen color using DOS output
   DOSLocate     sets the cursor position using DOS output
   DPutScreen    put an array onto an area of the screen
   DRecolor      recolor text of a specified color in an array
   DRecolorArea  recolor a block of text in an array
   DScrRest      restore a saved screen from an array or other memory
   DScrSave      save a screen to an array or other memory
   DWindowManager make a pop-up window in an array
   DWindowMan2   make a pop-up window in an array (with user-defined frames)
   DWindowMan3   make a pop-up window in an array (array-based parameters)
   DWindowMan4   make a pop-up window in an array (spartan version)
   DXQPrint      write text into an array
   EGARest7      restore a saved screen to an EGA SCREEN 7 display
   EGARest8      restore a saved screen to an EGA SCREEN 8 display
   EGARest9      restore a saved screen to an EGA SCREEN 9 display
   EGASave7      save an EGA SCREEN 7 display to an array
   EGASave8      save an EGA SCREEN 8 display to an array
   EGASave9      save an EGA SCREEN 9 display to an array
   EWindowManagerC display a pop-up window on an EGA or VGA graphics screen
   EXQPrintC     display text at high speed on an EGA or VGA graphics screen

                              Routine Reference



Display:
   FadeOut       clear the screen with special effects
   GetColor      get the current colors being used by BASIC
   GetCRT        determine whether the display is color or mono
   GetCRT2%      determine whether the display is color or mono
   GetEGA        see if an EGA is in use and get info about it
   GetEGA2%      see if an EGA is in use
   GetHGA%       see if a Hercules mono adapter is in use
   GetLine       get a row of text from a virtual or saved screen
   GetRows       see how many rows are on the screen
   GetRows2%     see how many rows are on the screen
   GetScreen     get an area of the screen into an array
   GetTVScreen   get video buffer address for TopView or compatible
   GetVGA        see if a VGA is in use
   GetVGA2%      see if a VGA is in use
   GetVGAPalette get the specified VGA palette settings
   GetVidMode    find out what mode the display is in and other information
   GQPrint       display text quickly in SCREEN 2 (CGA hi-res graphics)
   GrafPrint     display text at graphics coordinates in a specified size
   GrafRest      restore a saved CGA graphics screen
   GrafSave      save a CGA graphics screen to an array
   GXQPrint      display text quickly in SCREEN 1 (CGA lo-res graphics)
   GXQPrint1     display text quickly in SCREEN 1 (CGA lo-res graphics)
   HCls          clear screen in Hercules graphics mode
   HInit         initialize Hercules pages
   HLine         draw a line in Hercules graphics mode
   HMode         switch between text mode and Hercules graphics mode
   HPage         set the active display page for Hercules graphics mode
   HPrint        display text in Hercules graphics mode
   HSetPixel     plot a point in Hercules graphics mode
   HTestPixel    get the color of a point in Hercules graphics mode
   InsChr        insert a space onto the screen
   InsLine       insert a blank row onto the screen
   LScroll       scroll an area of the screen left
   PrintScreen   print the screen on a printer
   PutScreen     put an array onto an area of the screen
   QPrint        display text very quickly
   ReColor       change text of a selected color to a new color
   ReColorArea   change all text in a selected area to a new color
   RScroll       scroll an area of the screen right
   Scroll        scroll an area of the screen up
   ScrRest       restore a saved screen from an array
   ScrSave       save a screen to an array
   Scrunch       compress a screen in an array
   SetCGAColor   set various aspects of CGA colors
   SetRows       set the number of rows on the display
   SetVGAPalette set the specified VGA palette info
   Split         clear the screen by scrolling parts of it different ways

                              Routine Reference



Display:
   TypePrint     display text as if it is being typed
   UnCalcAttr    convert a color/attribute back into foreground and background
   UnScrunch     uncompress a "scrunched" screen
   UnSplit       restore a saved screen by scrolling it from different places
   UpdTVScreen   update screen from buffer under TopView or compatible
   VGARest13     restore a saved screen to a VGA SCREEN 13 display
   VGASave13     save a VGA SCREEN 13 display to an array
   WindowManager display a pop-up window
   WindowMan2    display a pop-up window (with user-defined frames)
   WindowMan3    display a pop-up window (array-based parameters)
   WindowMan4    display a pop-up window (spartan version)
   XMPrint       display text through DOS after converting it through a table
   XQPrint       display text very quickly

Equipment:
   CDROM         see if a CD-ROM is installed and get info about it
   CDROM2%       see if a CD-ROM is installed and get info about it
   Equipment     find out about basic equipment (ports and memory)
   ExtMem        see how much extended memory is available
   Floppies      see how many floppy drives are available
   Floppies2%    see how many floppy drives are available
   GetCRT        determine whether the display is color or mono
   GetCRT2%      determine whether the display is color or mono
   GetDOSV       get the DOS version
   GetEGA        see if an EGA is in use and get info about it
   GetEGA2%      see if an EGA is in use
   GetExtM       see how much extended memory is available
   GetHGA%       see if a Hercules mono adapter is in use
   GetLIMm       see how much expanded memory is available
   GetLIMv       get the EMS driver version
   GetVGA        see if a VGA is in use
   GetVGA2%      see if a VGA is in use
   GetXMSm       see how much XMS memory is available
   KbdType       see if the keyboard is an enhanced model (101-key)
   KbdType2      see if the keyboard is an enhanced model (101-key)
   MMCheck       see if a mouse is available and how many buttons it has
   NumProc       see what kind of numeric coprocessor is in use
   NumProc2%     see what kind of numeric coprocessor is in use
   PCDate        get the date of the ROM BIOS
   PCDat$        get the date of the ROM BIOS
   PCType        get the machine I.D. from the ROM BIOS
   PCType2%      get the machine I.D. from the ROM BIOS
   Processor     see what kind of CPU is in use
   Processor2%   see what kind of CPU is in use

                              Routine Reference



Input:
   AltKey        returns letter, given ASCII code and scan code of Alt key
   BarMenu       bar menu (single row) for keyboard only
   BarMenuM      bar menu (single row) for keyboard or mouse
   BIOSInkey     get a key from BIOS if any is waiting
   CheckKey      get a key if any is waiting, or a mouse button press
   CheckKey3     get a key if any is waiting, or a mouse button press
   ClrKbd        clear the keyboard buffer
   CtrlKey       returns letter, given ASCII code and scan code of Ctrl key
   DOSInkey      get a key from DOS if any is waiting
   DOSInky$      get a key from DOS if any is waiting
   EnhKbd        enable/disable enhanced keyboard handling
   GetKbd        get the status of the keyboard toggles (CapsLock, etc)
   GetKbd1       get the status of the shift keys (Control, Alt, etc)
   GetKbd2       get the exact status of the shift keys (Left/Right Alt, etc)
   GetKey        get a key or mouse click (wait for it; 2-button mouse)
   GetKey3       get a key or mouse click (wait for it; 3-button mouse)
   GetMouseLoc   get the mouse cursor position (text mode)
   GetValidKey   get one of a list of valid keys
   KbdType       see if the keyboard is an enhanced model (101-key)
   KbdType2      see if the keyboard is an enhanced model (101-key)
   KeyPress      see if a key is waiting to be retrieved
   MMButton      see which mouse buttons are pressed (2-button mouse)
   MMButton3     see which mouse buttons are pressed (3-button mouse)
   MMCheck       see if a mouse is installed and how many buttons it has
   MMClick       see which mouse buttons have been pressed (2-button mouse)
   MMClick3      see which mouse buttons have been pressed (3-button mouse)
   MMCursorOff   make the mouse cursor invisible
   MMCursorOn    make the mouse cursor visible
   MMGetLoc      get the mouse cursor position
   MMSetLoc      set the mouse cursor position
   MMSetRange    set the allowable range of the mouse cursor
   MouseBuffer   see how many bytes it will take to save the mouse state
   MousePen      turn light pen emulation by the mouse on/off
   MouseRest     restore a saved mouse state
   MouseSave     save the current state of the mouse
   PrtSc         disable the PrtSc/PrintScreen key
   ScanKey       get a key, if any is waiting, w/o taking it from the buffer
   SetKbd        set the state of the keyboard toggles (CapsLock, etc)
   SetMouseLoc   set the mouse cursor position (text mode)
   SInput        flexible replacement for LINE INPUT
   SInputSet     set parms for SInput (fill char, exit mode, beeps, fast)
   SInputSet1    set parms for SInput (cursor position, full exit)
   SInputSet2    set parms for SInput (capitalize, tab exit)
   SpeedKey      change the keyboard repeat rate
   TypeIn        stuff keys into the keyboard buffer as if they were typed

                              Routine Reference



Memory:
   BlockMove     copy data from one area of memory to another
   DataSeg       determine the default data segment (dgroup)
   EMSBuffer     get the bytes needed to save the EMS array state for CHAINing
   EMSClose      close an EMS array
   EMSGet        get an element from an EMS array
   EMSOpen       create an EMS array
   EMSPut        put an element into an EMS array
   EMSRest       restore the EMS array state
   EMSSave       save the EMS array state
   ExtGet        get data from extended memory
   ExtMem        see how much extended memory is available
   ExtPut        put data into extended memory
   FarPeek       get a byte from memory (like PEEK, but no need for DEF SEG)
   FarPoke       put a byte into memory (like POKE, but no need for DEF SEG)
   GetExtM       see how much extended memory is available
   GetLIMHandles get the number of EMS handles being used
   GetLIMm       see how much expanded memory is available
   GetLIMv       get the EMS driver version
   GetXMSm       see how much XMS memory is available
   LClose        close a block of expanded memory
   LGet          get a block of data from expanded memory
   LOpen         open a block of expanded memory
   LPut          put a block of data into expanded memory
   MemSwap       swap the contents of one area of memory with another

Miscellaneous:
   DRecDel       delete a record or element from an array
   DRecIns       insert a record or element into an array
   DOSErrM$      convert a DOS error code into a text message
   DOSInt%       execute a DOS function (like BASIC's CALL INTERRUPT)
   CatchError    set up to grab the exit code from a SHELLed program
   GetDView      see if DESQview is loaded
   GetError      get the exit code from a SHELLed program
   GetSwitch     get the DOS switch character
   GetSwitch2$   get the DOS switch character
   GetTView      see if TopView or a compatible multitasker is loaded
   GetTVScreen   get video buffer address for TopView or compatible
   HandleInfo    determine whether a handle refers to a file or a device
   IntVector     get the address of an interrupt handler
   Reboot        boot the computer (like Control-Alt-Del)
   RedirectIn    see whether input has been redirected
   RedirectOut   see whether output has been redirected
   SetError      set the exit code to return when your program ends

                              Routine Reference



Numeric:
   AddMatI       add a value to each element of an integer array
   AddMatL       add a value to each element of a long integer array
   Any2Dec       convert a number from any base into an integer
   Dec2Any       convert an integer to any base
   IVal%         convert a string to an integer
   KVal%         convert a string to a long integer divided by 1024
   LVal%         convert a string to a long integer
   Max%          return the greater of two integers
   MaxD#         return the greater of two double precision numbers
   MaxL&         return the greater of two long integers
   MaxS!         return the greater of two single precision numbers
   MeanAverageD  calculate the average value of a double precision array
   MeanAverageI  calculate the average value of an integer array
   MeanAverageL  calculate the average value of a long integer array
   MeanAverageS  calculate the average value of a single precision array
   Min%          return the smaller of two integers
   MinD#         return the smaller of two double precision numbers
   MinL&         return the smaller of two long integers
   MinS!         return the smaller of two single precision numbers
   MulMatI       multiply each element of an integer array by a value
   NumFormat     format a number as a string, just like PRINT USING
   Rand%         return a pseudo-random number in a specified range
   ReadBitF      read a value of a specified bit length from an array
   SetBit        set a specified bit in an integer
   SetMatI       set each element of an integer array to a given value
   SetMatL       set each element of a long integer array to a given value
   ShiftL        shift the bits in an integer left by a specified amount
   ShiftLL       shift the bits in a long integer left by a specified amount
   ShiftR        shift the bits in an integer right by a specified amount
   ShiftRL       shift the bits in a long integer right by a specified amount
   WriteBitF     write a value of a specified bit length into an array

Printer:
   CPrintScreen1 send a SCREEN 1 display to the printer
   CPrintScreen2 send a SCREEN 2 display to the printer
   PrintFile     send a file to the printer
   PrintScreen   print the screen on the printer
   PrtSc         disable the PrtSc/PrintScreen key
   PrtSwap       swap any two printer ports
   Spooler       see if the DOS print spooler (PRINT.COM) is loaded

Serial:
   Carrier       determine if a carrier is present
   Checksum      calculate a checksum on a string
   CRC           calculate a CRC for a string
   DTR           set the state of the DTR line
   GetCommAddr   get the address of a comm port
   SetComm       set communications parameters
   SetCommAddr   set the address of a comm port

                              Routine Reference



String:
   AscI%         get the ASCII value of a character (like ASC)
   Bickel        compare two strings using Bickel's algorithm
   BSq           compress the blanks out of a text string
   BUsq          restore a string that was compressed by BSq
   BUsqLen       determine the expanded length of a BSq-compressed string
   Checksum      calculate a checksum
   Cipher        perform simple string encryption/decryption
   CipherP       like the above, only the results are printable
   CRC           calculate a CRC
   Crunch        remove repeated values from a string
   DGetRec       get a string from memory organized in a record format
   DGetSt        get a string from a numeric array or other memory
   DPutRec       put a string into memory organized in a record format
   DPutSt        put a string into a numeric array or other memory
   Extract       extract a delimited substring from a string
   IStr$         convert an integer to a string
   Locase        convert a string to lowercase
   Locase1       convert a string to lowercase (International)
   LRotate       rotate the characters in a string left once
   MatchFile     see if a filename matches a filespec with wildcards
   Month         return the name of the month, given the month number
   MultiAND      perform an arithmetic AND operation on a string
   MultiOR       perform an arithmetic OR operation on a string
   MultiXOR      perform an arithmetic XOR operation on a string
   NameCase      convert a string to proper uppercase/lowercase for a name
   NameCase2$    convert a string to proper uppercase/lowercase for a name
   Replace       replace one character with another
   ReplaceString replace one substring with another
   Reverse       reverse a string
   RInstr        find the last occurrence of a substring within a string
   RRotate       rotate the characters in a string right once
   SFRead        read a string from a file
   SFWrite       write a string to a file
   Soundex       determine what a string "sounds" like
   SSrch         see if one string is within another
   StrDel        delete a character from a string
   StrIns        insert a space into a string
   Strip         strip the blanks from both sides of a string
   StripBlanks   strip the blanks from either or both sides of a string
   StripChar     strip a specified list of characters from a string
   StripRange    strip a specified range of characters from a string
   StripSpaces   strip the spaces from either or both sides of a string
   Strip2$       strip the blanks from both sides of a string

                              Routine Reference



String:
   StrSqu2       compress a text string using 2-gram compression
   StrSquLen2    determine the 2-gram compressed length of a text string
   StrUnsqu2     uncompress a 2-gram compressed string
   StrUnsquLen2  determine the full length of a 2-gram compressed string
   TInstr        search for a specific kind of character in a string
   Upcase        convert a string to uppercase
   Upcase1       convert a string to uppercase (International)
   Xlate         run each character of a string through a translation table

Time:
   CalcDate      returns the date a given number of days from a starting date
   CheckDate     checks a date to determine whether it is valid
   Clock         display a clock on the screen, constantly
   ClockSet      set the parameters for the clock
   Date2Int      squash a date into a single integer
   DateA2R       converts a date to a number that can be used in calculations
   DateN2S       convert a date from numbers into a string
   DateR2A       converts a number to a date
   DateS2N       convert a date from string form into numbers
   DCal          draws a calendar into an array which ScrRest can display
   DCalendar     draws a calendar and allows the user to select a new date
   Delay         delay for a given number of seconds
   Delay18th     delay for a given number of 18ths of seconds
   DelayV        delay for a very small amount of time
   Elapsed       determine the elapsed time between two times
   ElapsedTime$  determine the elapsed time between two times
   EuropeDate    convert a date to European format
   FormatDate    convert a date to any desired format
   GetDateA      get the date of a file matched by FindFirstA/FindNextA
   GetDateAT     get the date from the AT hardware clock
   GetDateF      get the date of a file matched with FindFirstF/FindNextF
   GetDateFx$    get the date of a file matched with FindFirstFx/FindNextFx
   GetFDate      get the date of a file
   GetFTime      get the time of a file
   GetTime       get the time from DOS, including 100ths of seconds
   GetTimeA      get the time of a file matched by FindFirstA/FindNextA
   GetTimeAT     get the time from the AT hardware clock
   GetTimeF      get the time of a file matched with FindFirstF/FindNextF
   GetTimeFx$    get the time of a file matched with FindFirstFx/FindNextFx
   Int2Date      unsquash a date from a single integer into numbers
   Int2Time      unsquash a time from a single integer into numbers
   Month         return the name of the month, given the month number
   Sec2Time$     convert from "seconds past midnight" to a time string
   SetDateAT     set the date of the AT hardware clock
   SetTimeAT     set the time of the AT hardware clock
   Time2Int      squash a time into a single integer
   Time2Sec&     convert a time string to a "seconds past midnight" value
   TimeN2S       convert a time from numbers into a string
   TimeS2N       convert a time from a string into numbers
   WeekDay       get the day of the week
   WeekDay1      returns the day of the week for a given date

                             Enhanced Key Codes



This is a list of the new key codes available when you use EnhKbd to enable
enhanced keyboard support.  Note that the codes are direct from the BIOS, and
may not always match what INKEY$ returns.  QuickBASIC 4.5 provides only
minimal support for the enhanced keys; QBX does much better.  As long as you
use PBClone for input, of course, you don't have to worry about it.

The format used is ScanCode, ASCIIcode.


Middle keypad key (num lock off):   0,76
Middle key, with Control:           0,143

             plain     shift     control     alt
             -----     -----     -------    -----
   F11       0,133     0,135      0,137     0,139
   F12       0,134     0,136      0,138     0,140

The middle cursor pad returns the same scan codes as the cursor/numeric pad
when NumLock is off, but with an ASCII code of 224 instead of 0.  If you want
the middle cursor pad and cursor/numeric pad to return the same values, you
should have your code do this:

   ' ...get key code...
   IF ASCIIcode = 224 AND ScanCode <> 0 THEN ASCIIcode = 0

Why use IF?  Because it is possible for the user to enter a plain 224 by
holding ALT and using the numeric keypad, which could cause confusion.

The arrows in the middle cursor pad will return special codes if pressed in
combination with an ALT key:

   up    arrow     0,152
   down  arrow     0,160
   left  arrow     0,155
   right arrow     0,157

Finally, the arrow keys on either cursor pad will return special codes if
pressed in combination with a CONTROL key:

                   middle pad     cursor/num pad
                   ----------     --------------
   up    arrow       224,141          0,141
   down  arrow       224,145          0,145
   left  arrow       224,115          0,115
   right arrow       224,116          0,116

                               DOS Error Codes



Note that the number of error codes available depends on the version of DOS
in use.  Older versions return fewer error codes, meaning that the nature of
the error may not be specified as precisely as you might like.  This is not a
complete list of all possible codes, but it covers the most common ones.

The DOSErrM$ function can be used to generate a complete error list if needed.


  -1    Unable to read or write all of the data requested
   0    No error
   1    Invalid function number (possible PBClone error)
   2    File not found
   3    Path not found
   4    No handle available (too many files open)
   5    Access denied (file already in use or marked "read only")
   6    Invalid handle
  15    Invalid disk drive
  16    Attempt to remove current directory
  18    No more matching files
  19    Disk is write-protected
  20    Unknown unit
  21    Drive not ready
  22    Invalid command
  23    Data CRC error
  25    Seek error
  26    Disk is not in DOS format
  27    Sector not found
  28    Printer is out of paper
  29    Write fault
  30    Read fault
  31    General failure
  32    Sharing violation
  33    Lock violation
  34    Invalid disk change
  35    No FCB available
  36    No room in file sharing buffer
  80    File already exists
  82    Unable to create subdirectory