Basic Building Blocks is a collection of assembler routines and
QuickBasic subprograms that I created and use for my own program
development as a self-employed programmer. Many of the routines
were inspired by commercial libraries that I purchased from the
major QB vendors, only to find them lacking or in need of
improvement. (However, I have been careful to use a "clean-room"
approach and write my routines from scratch.) My desire is to
make my routines as small, fast, and efficient as is practical,
and sometimes I even go way past being practical and stray into
fanatical.


All routines come with fully documented source code. I have made a
special effort to provide clean, clear, and complete documentation
within each source module itself. I've done this for two reasons:

1. I don't like having to reach for a manual every time I need to
check the syntax or function of a routine, so I did away with
the manual. Everything you need to know about a routine is in it.

2. I like code that is educational and teaches good programming
techniques by example. Much of my programming skill came from
studying other's code, and as a tribute to those individuals who
share their artistry (with high honors to Ethan Winer of Crescent
Software), I will do the same. There is as much art in creating
a descriptive narrative of computer code as there is in creating
efficient computer code in the first place. I try to do both.


To order the Basic Building Blocks diskette, complete the following form
(please print legibly) and send it with $35 to:




Martin Systems
120 Fence Post Court
Fountain, CO 80817





Diskette type: [ ] 360K [ ] 720K



Your name ___________________________________________________________


Address ___________________________________________________________


City ___________________________ State _______ Zip __________


Phone (______)___________________






Current version: 1.05

Supports: Microsoft QuickBasic versions 3.0, 4.0, 4.5
Microsoft PDS 7.1
Crescent Software's PDQ
Microsoft Visual Basic for DOS

Free updates are available for a one year period after the purchase date,
either by mail or modem. By mail, send a blank, formatted diskette and a
self-addressed, stamped diskette mailer (or send $4 and I'll provide the
diskette, mailer, and stamps). By modem, call (719) 382-8216 to reach
the BBS (2400 baud, N81).

If you think of a routine that would be a useful addition to this package,
please tell me and I will consider creating it. I am constantly adding
routines to the BBB library, which is why I'm offering free updates to
initial purchasers.


An example of the format used for all routines is shown below:
(Don't imagine that BBB routines are as trivial as this example!)


============================ Begin CENTER.BAS ============================

'Purpose: Centers text (or any other string) on screen.
'
' Syntax: call CenterText (text$, row)
'
' Pass: text$ String to center on screen.
' row Row where string will display.
'
'Returns: nothing
'
' Note: Row should be 1 to 25. String length should be <= 80.
' Screen width is assumed to be 80 characters. Initial
' cursor position is unchanged. Color used for display
' is current color.
'


defint a-z
sub CenterText (text$, row) static

OldRow = csrlin : OldCol = pos(0) 'save current cursor position
locate row, 41 - (len(text$)+1) \ 2 'place cursor where printing begins
print text$; 'display the text on-screen
locate OldRow, OldCol 'restore initial cursor position

end sub

============================= End CENTER.BAS =============================





List of current Basic Building Blocks routines (11/25/92):


BAS file Syntax and Use
--------- --------------

BITS call ChkBit (BitArray(), BitPos, BitOn)
call SetBit (BitArray(), BitPos, BitValue)
call ToggleBits (BitArray())
call CountSetBits (BitArray(), MaxBit, Count)
call FindNextBit (BitArray(), BitPos, BitValue, Direction, Found)

Collection of routines to manipulate individual bits in an integer
array.

BSEARCH1 call SearchStrArray (SearchStr$, Array$(), Rank(), ElementNum)
Binary search a string array that was "sorted" using pointers.

BSEARCH2 call SearchRecStr (SearchStr$, RecStr$, RecLen, rank(), RecNum)
Binary search a string containing fixed-length records that was
"sorted" using pointers.

BSEARCH3 call SearchStrArray (SearchStr$, Array$(), ElementNum)
Binary search a sorted string array.

CENTERQ call CenterText (Text$, row)
Centers a string on-screen at the desired row.
Uses PrintQ for fast screen writes.

CHKPATH call ChkPath (PathSpec$, found)
Reports if a path spec exists.

DATECNV call ConvertDate (DateStr$, NumDays, WeekDay)
call RestoreDate (NumDays, DateStr$)
Facilitates date arithmetic.

DELATTR call DelAttr (Text$, Action)
Removes embedded attribute chrs (used by PRINTQA) in a string.

DELAY call Delay (DelayTime!)
Produces a timed delay, regardless of computer speed.

DOTPROF call DotProfile (LowVal, HighVal, StepVal, StepLen, Score!, Graph$)
Draws a text-based, horizontal graph (like a thermometer graph).

DRAWBOXQ call DrawBoxQ (ulr, ulc, lrr, lrc, BoxChar, BoxColor)
Draws a box frame on-screen. Uses PrintQ for fast screen writes.

FCOPY call FCopy (Source$, Dest$, ErrorFlag)
Quickly copies a file to another location or file name.

GETCOLOR call GetColor (CurrentAttr)
Returns the current COLOR setting.

GETFIELD call GetField (row, col, MaxLen, FillChr, Text$, CrsrPos, EditCode)
Replaces INPUT statement with full editing and re-entrancy.
Uses PrintQ for fast screen writes.

HEADER '$include: 'header.bas'
Convenient first line for modules, sets constants.

INSSTR call InsStr (MainStr$, FindStr$, ReplaceStr$, Found)
A find & replace utility for text strings.

INTDELAY call IntDelay (DelayTicks)
Produces a timed delay, regardless of computer speed.

MENUBOXQ call MenuBoxQ (choice$(), prompt$(), BoxChr, Colors(), Flags, MenuChoice)
Displays a scrolling, bounce bar menu with item prompts.
Uses PrintQ for fast screen writes.

MENUBOX2 call MenuBox2 (choice$(), MenuChoice)
A simpler version of MENUBOXQ, smaller but fewer options.

MSGBOXQ call MsgBoxQ (message$(), TextColor, BoxChar, BoxColor, BoxWidth)
Display a window containing a message. Uses PrintQ for fast
screen writes.

PARSE call Parse (Text$, Delimiter$, StartPos, SubStr$)
General purpose re-entrant parser. Assumes one delimiter only.

PARSES call Parse (Text$, Delimiters$, StartPos, SubStr$)
General purpose re-entrant parser. Multiple delimiters allowed.

QSORT1 call SortStrArray (a$(), NumItems, rank())
"Sorts" a string array using pointers. QuickSort.

QSORT2 call SortFixedRecStr (RecStr$, RecLen, NumRec, rank())
"Sorts" fixed-length records in a record string using pointers.

QSORT3 call SortStrArray (a$(), NumItems)
Sorts a string array without using pointers. QuickSort.

SORT1 call SortStrArray (a$(), NumItems, rank())
"Sorts" a string array using pointers. Metz sort.

SORT2 call SortFixedRecStr (RecStr$, RecLen, NumRec, rank())
"Sorts" fixed-length records in a record string using pointers.

SORT3 call SortStrArray (a$(), NumItems)
Sorts a string array without using pointers. Metz sort.

STRIP call Strip (Text$, chr)
Strips strings of unwanted leading and trailing chrs.

VIEWFILE call ViewFile (FileName$)
File viewer to display the first 64K of a file.

WORDWRAP call WordWrap (ulr, ulc, lrr, lrc, Text$, Attr)
Wraps text within a user-defined area.

YESORNO call YesOrNo (KeyPressed)
Asks for a Yes or No response from operator.




ASM file Syntax and Use
--------- --------------

BBBTIMER call BBBTimer (ClockTicks&)
Small, fast replacement for the TIMER function.

CHECKKB call CheckKB (WaitFlag, KeyPressed)
Reads chrs from keyboard, optionally waiting for a key press.
Desqview, Windows, and OS/2 aware - releases time slice when
waiting for user input for optimal multitasking performance.

CHECKPRN CheckPrn (LPTPort, StatusCode)
Reports the specified parallel printer port status code.

CHNGCASE call ChngCase (Action, Text$)
Converts a string to upper/lower case.

CHNGCHRS call ChngChrs (Text$, FindChr, ReplaceChr)
Replaces all matching chrs in a string.

CHNGPATH Call ChngPath (NewPath$, PathErr)
Change current drive and directory in one operation.

CNTCHRS call CntChrs (r$, ChrCode, Count)
Quickly counts all occurances of a character in a string.

CRSRINFO call CrsrInfo (Row, Col, Visible, StartLine, EndLine)
Returns info about the cursor position, shape, and on/off status.

CRYPT call Crypt (Text$, Password$, Action)
Encrypts/decrypts any string.

DISKCNT Call DiskCnt (Drives)
Returns the number of logical drives in the computer system.

DISKINFO call DiskInfo (DriveLetter$, Bytes, Sectors, Clusters, ClustersFree)
Returns free space, used space, total space for desired drive.

EXIST Exist (FileName$, Found)
Reports if a file currently exists.

FCLOSE call FClose (Handle)
Fast, small routine to close a file open by FOpen or FCreate.

FCREATE call FCreate (FileName$, Handle)
Fast, small routine to open a new file for binary read or write.

FDELETE call FDelete (FileName$)
Small routine to delete a file without choking if it's not there.

FGET call FGet (Handle, Dest$, BytesRead)
Retrieves data from a file opened by FOpen or FCreate.

FOPEN call FOpen (FileName$, Handle)
Fast, small routine to open an existing file for binary read or
write.

FPUT call FPut (Handle, Source$, BytesWritten)
Writes data to a file opened by FOpen or FCreate.

FSEEK call FSeek (Handle, RecLen, RecNum)
Sets the read/write location in a file opened by FOpen or FCreate.

FILEDIR FileDir (FileSpec$, Segment, Offset)
Read file names from a directory into far memory.

FILEINFO call FileInfo (FileSpec$, Found, Info$)
Checks if a file exists and returns its attributes, size, and
date/time stamp in a string. QB4+ only (uses long integers).

GETCPU call GetCPU (ID)
Returns the current CPU type - 8088, 80286, 80386, or 80486.

GETFILES GetFiles (FileSpec$, DirList$)
Read file names from a directory into a string.

GETPATH call GetPath (PathSpec$)
Returns the default drive and directory.

GETVIDEO call GetVideo (VideoType)
Reports the video type - MDA, CGA, EGA, or VGA

INTTOSTR call IntToStr (Num, Num$)
Fast replacement for STR$(Num) for integers only.

INTTIME call IntTimer (ClockTicks)
Small, short-integer replacement of the TIMER function.

INTVAL call IntVal (r$, Integer)
Fast replacement of VAL(r$) for integers only.

LENA call LenA (Text$, DisplayLen, CutOff)
Calculates the display length of a string containing embedded
attribute characters (used by PRINTQA).

MIDCHAR call MidChar (Text$, ChrPos, ChrCode)
Returns ASCII code of any character in a string.
Like QB's ChrCode = asc(mid$(Text$,ChrPos,1)), only faster!

PAINTBOX call PaintBox (TRow, LCol, BRow, RCol, Attr)
Changes the color of a rectangular area on-screen without erasing
any text in the area. Desqview aware.

PRINTB call PrintB (Row, Col, Attr, Text$)
Displays strings on-screen using BIOS calls. Faster than most
routines using BIOS calls AND compatible with all IBM PC's.

PRINTQ call PrintQ (Row, Col, Attr, Text$)
Displays strings on-screen QUICKLY using direct screen writes.
Desqview aware.

PRINTQA call PrintQ (Row, Col, Attr, Text$)
Displays strings on-screen QUICKLY using direct screen writes.
Desqview aware. Can change colors on a per character basis
using embedded attribute codes in Text$

PTRINIT call PtrInit (NumElements, segment, offset)
Fast way to set the integer pointer array used by the sort routines.

PUTCHAR call PutChar (Text$, ChrPos, ChrCode)
Replaces any character in a string.
Like QB's mid$(Text$,ChrPos) = chr$(Chrcode), only faster!

REBOOT call ReBoot (BootType)
Reboots the computer using either a warm or cold reboot.

SCANSTR call ScanStr (StartPos, r$, ChrCode, Action, ChrPos)
Search a string forwards/backwards for the next character match/
nonmatch.

SCRLLBOX call ScrollBox (ULRow, ULCol, LRRow, LRCol, Action, ColorCode)
Scroll or clear a rectangular area on-screen. Desqview aware.

SCRNCOPY call ScrnCopy (Source, Destination)
Saves/restores two entire screen displays using simplified
parameters. Desqview aware.

SCRNSRA call ScrnSaveA (ULrow, ULcol, LRrow, LRcol, Segment, Offset)
call ScrnRestA (ULrow, ULcol, LRrow, LRcol, Segment, Offset)
Saves/restores a specified region of the display screen to an
integer array in far memory. Desqview aware.

SPEAKER call Speaker (Freq, Duration)
Small integer-only replacement for the SOUND command.

STRSAVE call StrSave (r$, segment, offset)
call StrRest (r$, segment, offset)
Saves/Restores a string to far memory (an integer array).

TESTPRN TestPrn (LPTPort, PrnOK)
Reports if printer is on-line and ready.

TIMEIT call IntTimer (Action, Ticks)
Small, short-integer stopwatch routine.




(Note: All utility programs listed below also include commented source code.)

Utility programs Use
---------------- ---

DISKINFO.EXE Reports hard drive partition sizes and percent free space.

FCOMP.EXE Finally got fed up with the DOS COMP program so I wrote
my own. Compares files, reports if they're different,
and sets ERRORLEVEL for batch file use.

LPTINFO.EXE Reports the printer status for all three LPT ports.

VIEW.EXE Compact ASCII file viewer.

XQB4CAPS.EXE Converts those $@#! upper case QB4 keywords in your source
code file to easier-to-read lower case, without affecting
anything else.

XDOT.EXE Converts old-style variable names containing periods in your
source file to variable names without periods.

Example: old.style.name => OldStyleName

Variable names using periods are so much easier to read, but
Microsoft would like to see them used only for user-defined
type fields.

WAIT.EXE Batch file utility that pauses operation for a specified
number of seconds (i.e. WAIT 5 pauses five seconds). A
key press will terminate the wait, and ERRORLEVEL is set
to the number of seconds elapsed before the key was pressed
or to zero if the wait was not interrupted.


Demo programs
--------------
Most routines are demonstrated with short, commented, example programs
(too numerous to list).



Recommended QB tools:
--------------------
Basic Building Blocks (of course) is the biggest programming bang for the
buck. Wish I'd had it when I started programming... $35

PDQ, from Crescent Software, allows QB programmer's to make small, fast
programs that approach the efficiency of assembler without the pain.
$149. 1-800-352-2742.

SMAK, my simple make utility. Makes compiling and linking from the command
line a joy. Especially useful with PDQ. Shareware ($25 registration).

BOXER, the programmer's editor that moved me from Brief (the commercial
standard). Shareware from David R. Hamel ($35 registration).

Note: SMAK and BOXER are both downloadable from my BBS at (719) 382-8216.



About the author (Hugh Martin):
----------------
Ever wonder about the people who do this kind of stuff? I do, so here's
a bit about me.

I earn my living as a computer programmer, consultant, and systems
integrator. I'm have two kids (Miriam - Apr 87 and Eric - Jan 91), who
are driving my wife and me crazy with their boundless energy. We are
energetic ourselves, preferring to ski, bicycle, play tennis, or hike,
but have been forced to put all that on low while we raise these little
rascals. We all speak both French and English at home, though Miriam
has discovered that English is much more universal in our neighborhood
and is insisting on using it more and more, despite having learned French
first. I'm a bit of a gourmet and like to grow my own vegetables because
they taste so much better. I keep a trampoline in the back yard and use
it regularly and expertly. Yes, like many computer people, I'm a little
bit strange. My neighbors don't understand a grown man doing flips on a
trampoline.

I'm an independent soul, and enjoy forming my own opinions. When
something breaks, I prefer to fix it myself, regardless of the time it
takes, because I know I'll learn something, and probably do a better job
than most repairmen. Learning, being independent, and doing the job
right are major motivators for me. I am a critical observer, and pay
close attention to details, but also tend to think globally. I'm betting
man will severely damage his own environment, but I'm basically an optimist.

Gee, doctor, I feel a lot better now. How much do I owe you?