Basic Programmer's Toolbox
(BPTB Version 1.0)
Copyright (c) 1992



The Basic Programmer's Toolbox is a collection of over 70 routines
and functions to help the Basic programmer bring their projects to
completion quickly and easily. The files included on this disk should
include:


BPTB.DOC Operations manual (This file)

QBXTLS.QLB Quick Library for use with PDS 7.1
QBXTLS.LIB LIB version for use with PDS 7.1
QBXTLS.INC Include file for PDS 7.1

QBTLS.QLB Quick Library for QB 4.5
QBTLS.LIB LIB version for use with QB 4.5
QBTLS.INC Include file for QB 4.5


None of these files or this documentation may be copied or
distributed without the written permission from the author. You are
free to use and distribute any program written using these routines
without any fee due only after completing the registration form, found
on the last page of this manual, and mailing it and the $25.00
registration fee to the author. You will get a copy of the source
code for my program EZDOS with your registration.

BPTB is written in both Basic and assembly. I have elected to
write all of the routines in the Quick Library in Basic due to the
methods MS uses with certain internal functions and variables. The
assembly version is only included in the linkable LIB library. You
will note vast differences in performance using these routines within
the environment compared to use in the compiled version of your
program.

The .LIB and .QLB files selected must be copied into the directory
listed under libraries in the "PATH" selection from the Quick Basic or
PDS menus. The .INC file should be copied into the directory listed
for include files under the same menu selection. Starting Quick Basic
or PDS with the "/L" switch will load the Basic Programmer's Toolbox
into your programming environment. ("QBX /L QBXTLS" or "QB /L QBTLS")

The first line of your program should use the DEFINT command to
set the default variable type to INTEGER and then use the $INCLUDE
metacommand to properly declare all of the routines in the library.
See your QB 4.5 or PDS 7.1 documentation for more on these commands.
( DEFINT A-Z )
( REM $INCLUDE: 'QBXTLS.INC' )

Note: All variables that are not explicitly declared are assumed to
be of the type INTEGER (%).

Basic Programmer's Toolbox 1.0 Page 1 of 14



Table Of Contents


Date / Time Routines
CLOCK............ 3 DAYOFWEEK........ 5
DATE2NUMBER...... 5 NUMBER2DATE...... 10

Display Routines
CENTER........... 3 LEFTSCROLL....... 8
CLEARSAVEDSCREENS 3 PAGEUP........... 10
COMMAS........... 4 PAGEDOWN......... 10
CURRENTCHAR...... 5 RESTORESCREEN.... 11
CURRENTCOLOR..... 5 RIGHTSCROLL...... 12
FADED............ 6 SAVEDSCREENS..... 12
FADEIN........... 6 SAVESCREEN....... 12
FADEOUT.......... 6 SETSAVED......... 12
FIRSTCAP......... 7 SHADOW........... 12
GETCOLOR......... 8

Disk Drive Routines
CHECKDRIVE....... 3 FILEEXISTS....... 6
COPYFILE......... 4 FILEINFO......... 7
CURDIR........... 4 FILESEARCH....... 7
CURDRIVE......... 5 FINDFIRSTFILE.... 7
DISKCAPACITY..... 5 FINDNEXTFILE..... 7
DISKSPACE........ 5 TREE............. 13
DRIVEOKAY........ 6

Keyboard Routines
ALTPRESSED....... 3 FLUSHKEYBOARDBUFF 7
CAPLOCKON ....... 3 KEYPRESSED....... 8
CARLOCKOFF....... 3 NUMLOCKOFF....... 10
CTRLPRESSED...... 4 NUMLOCKON........ 10

Mouse Routines
MOUSEBUTTON...... 9 MOUSEON.......... 9
MOUSEHORZ........ 9 MOUSESHOW........ 10
MOUSEINSTALLED... 9 MOUSEVERT........ 10
MOUSEOFF......... 9

System Routines
CHECKREBOOT...... 3 RUNPROGRAM....... 12
COPYMEM.......... 4 VIDEOMODE........ 13
DOSVERSION....... 6 VIDEOPAGE........ 13
NOREBOOT......... 10 VIDEOSEGMENT..... 14
REBOOT........... 11

User Interface Routines
CLOSEWINDOW...... 4 PASSWORD......... 11
GETINPUT......... 8 PICKWINDOW....... 11
INPUTBOX......... 8 PULLDOWN......... 11
MENUBAR.......... 9 USERCHOICE....... 13
MSGWINDOW........ 10 WINDOWCOLOR...... 14



Basic Programmer's Toolbox 1.0 Page 2 of 14



ALTPRESSED DECLARE FUNCTION altpressed% ()

Parameters: None.
Returns: -1 if alt key is pressed.
0 if alt key is not pressed.
Description: Returns the status of the keyboard's alt key at the
time the function is called.

CAPLOCKOFF DECLARE SUB caplockoff ()
CAPLOCKON DECLARE SUB caplockon ()

Parameters: None.
Returns: None.
Description: These routines force the Caps Lock on or off.

CENTER DECLARE SUB center (word$)

Parameters: word$ = string to be printed.
Returns: None.
Description: This routine will print the string passed in word$
centered equally right and left of the current
cursor location.

CHECKDRIVE DECLARE FUNCTION checkdrive% (drive$)

Parameters: drive$ = letter of drive to check. ("" for default)
Returns: 0 if drive is ready for I/O.
DOS error code if drive is not ready for I/O.
Description: Allows the programmer to check if a drive is ready
for I/O to avoid an unwanted DOS error.

CHECKREBOOT DECLARE FUNCTION checkreboot% ()

Parameters: None.
Returns: -1 if ALT-CTRL-DEL is disabled using noreboot.
0 if ALT-CTRL-DEL is not disabled.
Description: Will allow the programmer to know if the noreboot
routine has been called to disable the reboot
interrupt. (See noreboot routine)

CLEARSAVEDSCREENS DECLARE SUB clearsavedscreens ()

Parameters: None.
Returns: None.
Description: Resets the internal counter on the number of screens
saved using the savescreen routine.

CLOCK DECLARE FUNCTION clock$ ()

Parameters: None.
Returns: The current system time
Description: Will return the current system time in standard time
display format (11:37 AM).



Basic Programmer's Toolbox 1.0 Page 3 of 14



CLOSEWINDOW DECLARE SUB closewindow ()

Parameters: None.
Returns: None.
Description: closes a message window created with the msgwindow
routine.

COMMAS DECLARE FUNCTION commas$ (number#, places%)

Parameters: Number# = number to format.
places% = number of decimal places to display.
Returns: Formatted display of number passed in number#.
Description: Can be used to pass a formatted number (with commas)
to other print routines that require a string
parameter.

COPYFILE DECLARE SUB copyfile (from$, to$)

Parameters: From$ = Name of file to copy from.
To$ = Name of file to copy to.
Returns: None.
Description: Allows the programmer to copy a file without the
need to shell to DOS. This will avoid unwanted DOS
messages.

COPYMEM DECLARE SUB copymem (seg%, from%, to%, words%)

Parameters: Seg% = segment of memory to use.
From% = offset address to copy from.
To% = offset address to copy to.
Words%= number of "words" (2 bytes) to copy.
Returns: None.
Description: This will routine will copy the contents of one
memory location to another. Both locations must be
within the same memory segment. This routine copies
word length (2 bytes) sections only.

CTRLPRESSED DECLARE FUNCTION ctrlpressed% ()

Parameters: None.
Returns: -1 if ctrl key is pressed.
0 if ctrl key is not pressed.
Description: Returns the status of the keyboards ctrl key at the
time the function is called.

CURDIR DECLARE FUNCTION curdir$ ()

Parameters: None.
Returns: The name of the current default directory.
Description: Allows the programmer to find the current DOS
directory. This routine is included in the Quick
Basic library only.




Basic Programmer's Toolbox 1.0 Page 4 of 14



CURDRIVE$ DECLARE FUNCTION curdrive$ ()

Parameters: None.
Returns: Current DOS default drive letter.
Description: This routine allows the programmer to know what
drive is currently active.

CURRENTCHAR DECLARE FUNCTION currentchar$ ()

Parameters: None.
Returns: The character at the present cursor location.
Description: This routine allows the programmer to read the video
memory at the current cursor location.

CURRENTCOLOR DECLARE SUB currentcolor (fg%, bg%)

Parameters: None.
Returns: Fg% = current foreground color.
Bg% = current background color.
Description: This routine allows the programmer to know what the
current screen colors that the Basic program is
using are.

DATE2NUMBER DECLARE FUNCTION date2number& (day$)

Parameters: Day$ = Valid date (mm/dd/yy) to convert.
Returns: The Julian number for the date passed in day$.
Description: This routine will convert a valid date into the
corresponding Julian date. These numbers can then
be used to calculate the number of days between two
different dates.

DAYOFWEEK DECLARE FUNCTION dayofweek$ (day$)

Parameters: Day$ = Valid date (mm/dd/yy) to check.
Returns: The day of the week that the date in day$ falls
on ("Wednesday").
Description: This routine allows the programmer to determine what
day of the week a date falls on.

DISKCAPCITY DECLARE FUNCTION diskcapacity& (drive$)

Parameters: Drive$ = letter of drive to check.
Returns: Total capacity of the specified disk.
Description: This routine will inform the programmer of the
capacity of any drive on the system.

DISKSPACE DECLARE FUNCTION diskspace& (drive$)

Parameters: Drive$ = letter of drive to check.
Returns: Total free space of the specified disk.
Description: This routine will inform the programmer of the
current free space of any drive on the system.



Basic Programmer's Toolbox 1.0 Page 5 of 14



DOSVERSION DECLARE FUNCTION dosversion! ()

Parameters: None.
Returns: DOS version number
Description: This will allow the programmer to know what version
of DOS the program is running under.

DRIVEOKAY DECLARE FUNCTION driveokay% (drive$)

Parameters: drive$ = drive letter to check.
Returns: -1 if drive is ready for I/O.
0 if drive is not ready for I/O.
Description: This routine will allow the programmer to check a
given drive to avoid a DOS error.

FADED DECLARE FUNCTION faded% ()

Parameters: None.
Returns: -1 screen has been faded with the fadeout routine.
0 screen has not been faded.
Description: Allows the programmer to test if screen has been
faded using the fadeout routine.

FADEIN DECLARE SUB fadein ()

Parameters: None.
Returns: None.
Description: restores a screen that has been faded with the
fadeout routine. NOTE: SEE FADEOUT ROUTINE.

FADEOUT DECLARE SUB fadeout ()

Parameters: None.
Returns: None.
Description: Fades a display screen to total black and saves the
original screen. It is okay to draw new screens
while faded and then restore the new screen with the
fadein routine. NOTE: This routine has been tested
with EGA and VGA only. CGA cards might have
problems with the fadein and fadeout routines.

FILEEXISTS DECLARE FUNCTION fileexists% (name$)

Parameters: name$ = File name (and path) to check.
Returns: -1 if file exists.
0 if file does not exists.
Description: This routine allows the programmer to determine if a
given file exists.








Basic Programmer's Toolbox 1.0 Page 6 of 14



FILEINFO DECLARE SUB fileinfo (dta$,name$,size&,day$)

Parameters: dta$ = Disk Transfer Data returned by findfirstfile
or findnextfile routines.
Returns: name$ = Name of file returned.
size& = Size of file returned.
day$ = date of file returned.
Description: This routine allows the programmer to "de-code"
information returned from the find file routines.

FILESEARCH DECLARE SUB filesearch (path$, name$(),
size&(), when$(), count%)

Parameters: Path$ = Path and/or name of the file to search for.
DOS wild-cards (* , ?) may be used.
Returns: Name$()= array of file names found.
size&()= array of file sizes found.
when$()= array of file dates found.
count% = Number of matching files found.
Description: With this routine the programmer can extract file
information on a group of files.

FINDFIRSTFILE DECLARE SUB findfirstfile (path$,dta$,result%)

Parameters: Path$ = file specification to search for. DOS
wild-cards (*,?) are permitted.
Returns: Dta$ = DOS disk transfer area information.
Result= 0 if a match was found or > 0 if no match is
found.
Description: This routine (along with findnextfile routine)
allows the programmer to search for and retrieve
information on a group of files.

FINDNEXTFILE DECLARE SUB findnextfile (path$,dta$,result%)

Parameters: Same as Findfirstfile
Returns: Sane as Findfirstfile
Description: See Findfirstfile. This routine is used to search
for the second and higher matching files.

FIRSTCAP DECLARE FUNCTION firstcap$ (word$)

Parameters: word$ = string to convert.
Returns: A copy of word$ with the first letter upper case and
the rest lower case.
Description: This routine can be used to assure all user input is
formatted the same for displays.

FLUSHKEYBOARDBUFF DECLARE SUB flushkeyboardbuff ()

Parameters: None.
Returns: None.
Description: This routine removes anything remaining in the
keyboard buffer.


Basic Programmer's Toolbox 1.0 Page 7 of 14



GETCOLOR DECLARE SUB getcolor (fg%, bg%)

Parameters: None.
Returns: Fg% = foreground color.
Bg% = background color.
Description: This routine returns color information about the
display area at the current cursor location.

GETINPUT DECLARE SUB getinput (word$, length%, scode%)

Parameters: word$ = string to edit (optional).
length = max number of characters to input.
Returns: word$ = copy of the user input.
scode = scan code of extended keys if one was
pressed.
Description: This routine allows the programmer to restrict the
number of characters the user may enter. Pressing a
"F" key will exit this return and return the scan
code for the key pressed in scode.

INPUTBOX DECLARE SUB inputbox (word$,length%,scode%,
fg%,bg%)

Parameters: word$ = string to edit (optional).
length = max number of characters to input.
fg = foreground color of input box.
bg = background color of input box.
Returns: word$ = copy of user input.
scode = scan code of extended keys if one is
pressed.
Description: This routine is the same as getinput, but allows
the programmer to draw a input box in their choice
of color.

KEYPRESSED DECLARE FUNCTION keypressed$ ()

Parameters: None.
Returns: The key that was pressed.
Description: This routine will wait for the user to press a key
and will return the key that was pressed.

LEFTSCROLL DECLARE SUB leftscroll (a$)

Parameters: a$ = The string to display.
Returns: None.
Description: The string passed in a$ will be displayed at the
current cursor location one letter at a time.









Basic Programmer's Toolbox 1.0 Page 8 of 14



MENUBAR DECLARE SUB menubar (menu$())

Parameters: menu$() = See "pulldown" routine.
Returns: None
Description: This routine will draw the main menu bar that will
be used by the pulldown routine. This routine will
only need to be called if the programmer wants to
display this menu bar before a call to pulldown is
made.

MOUSEBUTTON DECLARE FUNCTION mousebutton% ()

Parameters: None.
Returns: The status of the mouse buttons at the time a call
to this routine is made.
Description: This routine is used to test the status of the mouse
buttons. Possible returns are:
0 = No button pressed.
1 = Left button pressed.
2 = Right button pressed.
3 = Left and right button pressed.
4 = Center button pressed
5 = Left and center button pressed.
6 = Right and center button pressed.
7 = All three buttons pressed.

MOUSEHORZ DECLARE FUNCTION mousehorz% ()

Parameters: None.
Returns: Current horizontal location of mouse cursor.
Description: Used to get location of mouse cursor.

MOUSEINSTALLED DECLARE FUNCTION mouseinstalled% ()

Parameters: None.
Returns: -1 if mouse driver has be initialized properly.
0 if mouse driver has not been initialized.
Description: This routine allows the programmer to test if the
mouse driver is present and ready to operate.

MOUSEOFF DECLARE SUB mouseoff ()

Parameters: None.
Returns: None.
Description: This routine will turn the mouse cursor off.

MOUSEON DECLARE SUB mouseon ()

Parameters: None.
Returns: None.
Description: This routine will install the mouse driver and
activate the mouse cursor. This routine must be
called before any other mouse function will work.



Basic Programmer's Toolbox 1.0 Page 9 of 14



MOUSESHOW DECLARE SUB mouseshow ()

Parameters: None.
Returns: None.
Description: This routine will turn the mouse cursor on after a
call to mouseoff.

MOUSEVERT DECLARE FUNCTION mousevert% ()

Parameters: None.
Returns: Current vertical location of mouse cursor.
Description: Used to get location of mouse cursor.

MSGWINDOW DECLARE SUB msgwindow (msg$())

Parameters: msg$() = message lines to display.
Returns: None.
Description: Opens a window and displays the message lines passed
in msg$(). This routine will automatically size the
window and will locate it in the center of the
screen. Use the closewindow routine to remove the
message window when complete.

NOREBOOT DECLARE SUB noreboot ()

Parameters: None.
Returns: None.
Description: The first call to this routine will disable the
Ctrl-Alt-Delete reboot process. A second call to
this routine will enable the reboot process.
This routine will only work in your compiled version
of the program.

NUMBER2DATE DECLARE FUNCTION number2date$ (number&)

Parameters: Number& = Julian number to decode.
Returns: A string containing the date represented by number&.
Description: Decodes the Julian date number.

NUMLOCKOFF DECLARE SUB numlockoff ()
NUMLOCKON DECLARE SUB numlockon ()

Parameters: None.
Returns: None.
Description: These routine force the number lock key on or off.

PAGEUP DECLARE SUB pageup (page%)
PAGEDOWN DECLARE SUB pagedown (page%)

Parameters: page% = video page to copy.
Returns: None.
Description: This routine will copy the contents of the video
page% to the current display memory by scrolling the
new page either up, or down.


Basic Programmer's Toolbox 1.0 Page 10 of 14



PASSWORD DECLARE FUNCTION password% (word$)

Parameters: word$ = An Authorized password set by user.
Returns: -1 if password matches.
0 if password does not match.
Description: This routine opens a window and asks the user to
enter a password. It compares the user input to the
password in word$ and returns the result. If the
password does not match, a warming message is
displayed before the routine returns.

PICKWINDOW DECLARE FUNCTION pickwindow% (title$, msg$())

Parameters: title$ = title line to display in window.
msg$() = array of possible selection text.
Returns: the number of the item selected by the user.
Description: Allows the programmer to open a selection window for
the user to enter a choice. The user can use the
cursor keys, the mouse, or the items number to make
a selection.

PULLDOWN DECLARE SUB pulldown (menu$(), main%, sub%)

Parameters: Menu$() = This must be "DIM" as an array 10 x 10
(DIM menu$(10,10)). Element 1,0 will hold
the first "Main Menu" name, 2,0 the

second, etc. Element 1,1 would hold the
first choice for Main Menu 1,0's selection
list. The first letter of each Main Menu
selection list must be a different letter
to allow the user to make a selection by
pressing a letter key.
Returns: main% = Number of the main menu selected.
sub% = Number of the selected option.
Description: This complete pulldown menu system will allow your
user to make selections by using the cursor keys,
by using a mouse, or by typing the first letter of
the selection wanted.

REBOOT DECLARE SUB reboot ()

Parameters: None.
Returns: None.
Description: This routine will perform a cold reboot of the
user's system.

RESTORESCREEN DECLARE SUB restorescreen ()

Parameters: None.
Returns: None.
Description: This routine will restore the last video display
saved using the savescreen routine.




Basic Programmer's Toolbox 1.0 Page 11 of 14






RIGHTSCROLL DECLARE SUB rightscroll (a$)

Parameters: a$ = string to display.
Returns: None.
Description: See leftscroll

RUNPROGRAM DECLARE SUB runprogram (a$)

Parameters: a$ = program name to run.
Returns: None.
Description: This routine will allow you to end your program and
run any other type of program including batch files
and .com programs. It must be noted that this
routine will work in your compiled program, but will
not work from within QB or PDS.

SAVEDSCREENS DECLARE FUNCTION savedscreens% ()

Parameters: None.
Returns: Number of screens in the savescreen routine buffer.
Description: Allows the programmer to check status of the
savescreen routine buffer.

SAVESCREEN DECLARE SUB savescreen ()

Parameters: None.
Returns: None.
Description: Saves the current video display to a savescreen
buffer in video memory. Note: You are only allowed
to save 7 screens without a restorescreen command.

SETSAVED DECLARE SUB setsaved (number%)

Parameters: number% = number of highest saved screen to keep.
Returns: None.
Description: Allows the programmer to reset the savedscreen
routines buffer are. all screens higher than
number% will be lost.

SHADOW DECLARE SUB shadow (number%)

Parameters: number% = number of columns to shadow.
Returns: None.
Description: This routine is used to display the shadows around
different windows in the library.








Basic Programmer's Toolbox 1.0 Page 12 of 14



TREE DECLARE SUB tree (drive$, display$(),
dirname$(), count%)

Parameters: drive$ = drive letter to use.
display$() = array to hold graphical display of
tree. I suggest that this array be DIM
to 250.
dirname$() = array to hold proper name of each
directory found.
Returns: display$() = a graphical display of the complete
directory tree. Each element in the
array will carry the next directory in
the tree.
dirname$() = a parallel array to display$() that
will contain the proper directory name
for each directory found.
count% = the total number of directories found.
Description: Allows the programmer to both read and display
directory information for the user's system.

USERCHOICE DECLARE FUNCTION userchoice$ (str$, f%, m%)

Parameters: str$ = string of ever allowable user selection.
f% = 0 if you do not want to return if a "F" key
is pressed or 1 if you do.
m% = 0 if you do not want to return if a
mousebutton is pressed or 1 if you do.
Returns: The users selection.
f% = if f%=1 at the call it will return the "F" key
number if one was pressed (1-10). If m%=1 at
the call it will return the vertical position
of the mouse cursor at the time a mousebutton
was pressed.
m% = if m%=1 at the call it will return the
horizontal position of the mouse at the time a
mousebutton was pressed.
Description: Allows the programmer to ask for the user's
selection and restrict the possible keys that
can be used.

VIDEOMODE DECLARE FUNCTION videomode% ()

Parameters: None.
Returns: The current video mode setting.
Description: Allows the programmer to test for the current video
mode setting.

VIDEOPAGE DECLARE FUNCTION videopage% ()

Parameters: None.
Returns: The current video display page.
Description: Allows the programmer to test for the active video
display page.



Basic Programmer's Toolbox 1.0 Page 13 of 14



VIDEOSEGMENT DECLARE FUNCTION videosegment% ()

Parameters: None.
Returns: The video segment of the user's system.
Description: Allows the programmer to know where the user's video
display memory is located.

WINDOWCOLOR DECLARE SUB windowcolor (fg%,bg%)

Parameters: fg% = foreground color to use.
bg% = background color to use.
Returns: None.
Description: Allows the programmer to select what color the
various window and menu routines will use.


*********************************************************************
Registration Form


Name: ________________________________________________________

Address: ________________________________________________________

City: __________________________ ST: _____ ZIP: ____________



Where did you find your copy of BPTB? ___________________________

What size disk do you want your copy on? 5 1/4" ____ 3 1/2" ____

Comments Are Always Welcome:

_____________________________________________________________________

_____________________________________________________________________

_____________________________________________________________________


Please mail this form and the $25.00 registration fee to:

Bill Smith
104 Brentwood Way
Simpsonville, SC 29681




Note: I now maintain a file area on "The Programmer's Forum" at
(803) 862-4616 that will always have the current version of
this and all my software. Downloads are permitted on the first
call.


Basic Programmer's Toolbox 1.0 Page 14 of 14