Category : BASIC Source Code
Archive   : QB4TB523.ZIP
Filename : MIXED.DOC

MIXED-LANGUAGE TOOLBOX FOR QuickBASIC
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
By Christy Gemmell


These are native QuickBASIC functions and procedures which call the
machine-code routines in the Assembly-Language Toolbox for QuickBASIC.
To use them, you must link both TOOLBOX.LIB, from the Assembly-Language
Library disk, and the copy of MIXED.LIB from the Mixed-Language Library
disk to your stand-alone programs, like this:

LINK yourprog,,,toolbox.lib mixed.lib;

Since the QuickBASIC environment only allows one Quick Library to be
loaded at a time, however, the version of MIXED.QLB supplied also
contains all the routines from TOOLBOX.LIB. This allows you to use the
environment to develop and test programs which use functions from
both libraries. Just start QuickBASIC with the command:

QB(X) yourprog /L mixed.qlb

You can even build your own Quick Libraries, incorporating Toolbox
routines, using the QuickBASIC Linker as follows:

LINK /QU yoursub.obj yourfun.obj toolbox.lib mixed.lib,,bqlb45.lib;

BQLB45.LIB is the special interface library supplied with Microsoft's
QuickBASIC 4.5 compiler. Substitute the following library names for other
versions of the language.

BQLB40.LIB for QuickBASIC 4.0
BQLB41.LIB for BASIC 6.0
QBXQLB.LIB for BASIC 7.0 and 7.1 PDS

Be sure that, whichever interface library you use, it can be found by
LINK.EXE when the library is being built. This can be done, either by
copying it to the Linker's own directory or to a subdirectory pointed to
by a LIB= environment variable in your AUTOEXEC.BAT file, for example:

SET LIB=C:\QB45\LIBRARY

See your MS-DOS or PC-DOS manual for more information about environment
variables.

If you have the Professional version of the Assembly-Language Toolbox,
of course, building customised libraries is much easier since a full
set of object (.OBJ) modules, together with source code, is supplied
with this release.

The stand-alone (.LIB) and Quick Library (.QLB) versions of the Mixed-
Language Toolbox both contain the following SUB programs and FUNCTION
procedures:


BARMENU

Creates and operates a menu orientated horizontally on the screen row
specified. The calling program must supply :

Row% = The screen row on which the menu bar will appear.
Atr% = The display attribute or colour for the menu bar.
Opt% = Number of options available for selection.
Menu$() = String array containing selection list. Menu$(0) should
be set to a string of ASCII characters, corresponding to
the initial or key letter of each option in the list.
Insert a space at the appropriate position of an option
to be disabled. In the remaining option strings an
ampersand '&' indicates that the next character is the
Hotkey to be highlighted for that option.
Bar% = The menu selection to be highlighted on entry into the
procedure.
Nxt% = If set, this flag just causes the menu to be refreshed
without pausing for a selection from the user. This is
used to handle presses on the Right or Left Arrow keys
in the Pull-Down Menu procedure.
Ctx% = If set, this flag indicates that context-sensitive help
is available, in which case ...
Tpc$ = The root name of the Topic file to be displayed if the
user presses for help. The current selection number
is appended to this to produce the actual filename.

eg, if Tpc$ = "CONFIG" and Bar% = 3

HelpMate (see TOOLBOX.DOC) will look for a Topic file
named CONFIG3.HLP.
Mouse% = If set, this flag indicates that a mouse is installed
and can be used to make selections.
HotKeys% = If set, this flag allows hotkeys to go directly to a
selection without you having to press as well.

DECLARE SUB BarMenu (Row%, Atr%, Opt%, Menu$(), Bar%, Nxt%, Ctx%,_
Topic$, Mouse%, HotKeys%)

On completion the procedure returns with the following variable set:

Bar% = Number of selection made by user. If zero then the
key was pressed to abort the procedure
without making a selection.

VERMENU (see below) is a similar procedure which operates a vertically
orientated point-and-shoot type menu.

See the source code of DEMON.BAS, the Toolbox demonstration program, for
examples of BARMENU and VERMENU in use.


BINDEC

Translates a string of binary digits to their long integer decimal
equivalent.

DECLARE FUNCTION BinDec& (Binary$)


CAPITAL

Converts all alphabetic characters in a string to lower-case,
except for the first character of each word, which is forced
to upper-case.

DECLARE FUNCTION CapItal$ (Original$)

This function is designed for use in printing address labels
and can correctly identify and format proper surnames like
'McLaughlin'.


CENTRE

Centres the string supplied within an empty string of specified width.

DECLARE FUNCTION Centre$ (Text$, MaxWidth%)

This function is called by the VERMENU routine (see below) to centre the
title of a pull-down menu within the window it refers to.


CHECKPRINTER

This procedure checks if the specified parallel printer is ready and
on-line. If so, it returns immediately with Ready% set to -1 (TRUE), if
not, CHECKPRINTER displays the message 'PRINTER NOT READY' on the bottom
row of the screen and waits for the operator to correct the problem and
press a key.

If the user presses , the procedure returns with Ready% set to
zero (FALSE). Any other keystroke causes it to go back and test the
printer again. CHECKPRINTER will not return until either the printer is
ready for output, or the key is pressed.

DECLARE SUB CheckPrinter (Printer%, Ready%)

Printer% is the number of the parallel printer to test (1 = LPT1: etc).

Example: CheckPrinter 1, Ready% ' Test LPT1:
IF NOT Ready% THEN
STOP
ELSE
LPRINT Stuff$
END IF


DATEINPUT

Accepts and verifies date input in a Reverse Video entry panel, all the
usual editing keys are supported and entry is terminated by either a
Carriage Return or one of several special function keys (see below).

DECLARE FUNCTION DateInput$ (Default$, Context%, Topic$, HotKey%)

Default$ = default string which can be accepted by just pressing
the key.
Context% = set TRUE if context-sensitive help is available, in
which case ...
Topic$ = name of the HELP Topic file to display whenever the
key is pressed.
HotKey% = If entry is terminated by anything other than the
key, this variable will contain an explanatory
return code ..

Return Codes: 1 = abort entry returning a null string
2 = repeat previous entry for this field
3 = pressed, move to previous field
4 = pressed, move to next field
5 = pressed, move to top of screen
6 = pressed, move to end of screen

Editing Keys: = Move cursor one character to the left
= Move cursor one character to the right
= Move cursor to first character of field
= Move cursor to last character of field
= Clear from current cursor position to
the end of the entry field.
= Replace character under cursor with a
blank space and move cursor one character
to the left.
= pop up on-line HELP screen.

DATEINPUT is designed to be used as part of a full-screen data-entry
system. Your program can examine the return code to determine whether
the operator wishes to terminate entry or move forwards or backwards
between entry fields.

See also the REVINPUT function for a similar, more general-purpose,
data-entry routine.


DAYSBETWEEN

Calculates the number of days between two dates, supplied as strings in
the format DD/MM/YYYY. The function will provide accurate results when
supplied with dates between 01/01/1901 and 31/12/2099.

DECLARE FUNCTION DaysBetween& (Date1$, Date2$)

See the INTERVAL function for a method of calculating the number of
days between two Julian dates.


DECBIN

Translates a decimal number to an equivalent string of binary digits.

DECLARE FUNCTION DecBin$ (Decimal&)


DOSVERSION

Gets the current Operating System (DOS) version. The version is returned
as a string in the form "3.20" (for DOS 3.2).

No calling parameters are required.

DECLARE FUNCTION DosVersion$ ()

The correct version will be returned, even under DOS 5.0 with SETVER
set to report otherwise.


FINDFILE

This function can be used to locate a particular file in any drive or
directory of the current system. Supply it with a pathname or an ambiguous
filespec and it will display a list of all matching files from which the
user can select the one required by highlighting it with the cursor arrow
keys. The function returns the full pathname of the file selected or a
null string if was pressed.

DECLARE FUNCTION FindFile$ (FileSpec$, Attr%, Mouse%)

FileSpec$ = Pathname of file to be located. It can include a drive
letter and the filename may be ambiguous if you use the
wildcard characters '*' or '?'.

Attr% = The display attribute for the file selection box if more
than one match is expected. If Attr% = 0 the function
uses default colours - Black on Cyan for colour monitors
and inverse video for monochrome monitors.

Mouse% = set this to TRUE (non-zero) if mouse support is required.

On entry, FILESPEC$ should contain the name of the file to be located. If
the filespec is ambiguous, the program presents a directory listing, in a
popup window, of all files which match and allows the operator to select
the actual one required. If the pathname is explicit, FindFile just checks
if it actually exists. On return FILESPEC$, will contain the full pathname
of the selected file, or a null string if it was not located (or the
key was pressed).


GETFLAG

The MIXED-LANGUAGE Toolbox includes a pair of functions which give you
access to the INTRA-APPLICATION COMMUNICATION AREA (IAC), an area of
memory which has been reserved, by DOS, so that programs can communicate
with each other. The IAC is 16 bytes long and is located, in low RAM at
addresses 0000:04F0 - 04FF (Hex). Once set, an IAC flag retains it's value
until you reset it or the computer is rebooted.

This function returns the value of one of the IAC flag bytes (1 to 16).

DECLARE FUNCTION GetFlag% (Flag%)

You can set the current setting of a particular IAC flag byte with the
SETFLAG function.

Since QuickBASIC programs, compiled with the /O switch to run stand-alone,
cannot pass variables to chain modules, you can use this feature to
implement a limited form of parameter passing.


GRATTRIB

Calculate display attribute for graphics modes, given the foreground
and background colours required.

DECLARE FUNCTION GrAttrib% (ForeGround%, BackGround%)

GRATTRIB calculates the attribute value which controls the foreground and
background colours of characters displayed using the GRAPRINT, CGATEXT,
MCGATEXT and VGATEXT procedures. It translates them using the formula:

Attribute% = (BackGround% * 256) + ForeGround%

Make sure that you use foreground and background colour values appropriate
to the SCREEN mode currently in use.

The ATTRIBUTE function provides a similar service for use with text mode
screens


ISDIR

This routine tests to see if the supplied string is the name of a
directory. To do this a local error handler is established to trap any
run-time errors and an attempt is made to change to the directory
specified in TEST$. If an error occurs then ISDIR% is set to Boolean FALSE
(zero), otherwise TRUE (-1) is returned.

DECLARE FUNCTION IsDir% (Test$)

ISDIR is used by the FINDFILE function when searching for files on another
drive or directory.


LEGALNAME

This function returns TRUE or FALSE to indicate if the filespec passed to
it is legal. To do this, each character in the string is compared with a
set of illegal characters. If none are found a further check is made to
ensure there are no more than eight characters in the name and three in
the extension.

FUNCTION LegalName% (FileSpec$)


LINEUP

Returns a string representation of a numeric value. If COMMA% is TRUE
(non-zero) then the string has commas inserted between every group of
three digits to the left of the decimal. If LENGTH% is non-zero then the
resulting string is left padded with spaces to produce a string of the
required length. If CURRENCY$ is not null, the character it contains will
be prefixed to the returned string.

DECLARE FUNCTION LineUp$ (Num#, Places%, Comma%, Length%, Currency$)


LONGDATE

This function accepts a three-part numeric date and transcribes it into
a string containing the date in words. This includes the day of the week,
which is obtained by calling DOS's internal time and date services. DOS
is also used to check for an invalid date.

DECLARE FUNCTION LongDate$(Day%, Month%, Year%)

LONGDATE returns a null string if the arguments passed evaluate to an
illegal date (eg 29/2/1989).


MATCH

Returns the starting position of a string of characters within
a larger string.

DECLARE FUNCTION Match% (Start%, Search$, Pattern$)

Call with: Start% = character position in search string to
start searching from
Search$ = String to search
Pattern$ = String expression to search for

Returns: Position of first character of Pattern$ in Search$
(0 if Pattern$ is not found)

Wildcards: # match any numeric character
! match any alphabetic character
? match any character

\ indicates that the next character in the string
to search for is literal, not a wildcard.

This function is similar to INSTR but allows the use of wildcards. It is
based on the MATCH function provided by Digital Research's C-BASIC.


MEDIA

Gets or sets the volume label and/or serial number of the specified
disk drive. Also returns the file system (FAT) type. This procedure
only works with DOS 5.0 or greater.

DECLARE SUB Media (Set%, Drive$, Volume$, Serial$, FileSy$)

Set% = FALSE (zero) Get media information.
TRUE (non-zero) Set media information.
Drive$ = The drive letter of the disk to be processed. A colon
may be included although it is not necessary. If Drive$
is a null string then the default, currently-logged,
drive is assumed.
Volume$ = The disk volume label (maximum 11 characters). If this
is a null string and Set% = TRUE, then the existing label
is not changed. To blank out an existing volume label,
fill Volume$ with at least one ASCII space character,
Serial$ = The disk serial number (8 hexadecimal characters). If
this is a null string and Set% = TRUE, then the existing
serial number is not changed. When setting a new serial
number do not include the intervening colon.
FileSy$ = The file system in use on the specified drive. Under DOS 5
this is either 12-bit or 16-bit FAT. Provided for information
only, you cannot change it except by reformatting the drive.

Note that the Volume Label is the one written that is written into the
Boot Record when the disk is formatted and is not necessarily the same
as the one set or returned by the DOS LABEL command.


NEXTWORD

Extracts the first word from a string.

DECLARE FUNCTION NextWord$ (Last$)

This function extracts the first complete word from a string of
text and pads it with a single leading and trailing space. The
returned word is actually removed from string which was passed
to NEXTWORD so the function can be called repeatedly to extract
each word until LAST$ is empty.


PANEL

This procedure is used to produce rectangular boxes, upon the video
display, of various shapes and colours. The calling program should supply
the row/column co-ordinate of the top, left-hand corner of the required
panel, its height in rows and width in columns. You should also specify
the display attribute that the panel will be displayed in and the border
style to frame it with.

DECLARE SUB Panel (Row%, Col%, Rows%, Cols%, Border%, Attr%)

Panels can be drawn with the following border styles:

ÚÄÄÄ¿ ÉÍÍÍ» ÖÄÄÄ· ÕÍÍ͸
³ 1 ³ º 2 º º 3 º ³ 4 ³
ÀÄÄÄÙ ÈÍÍͼ ÓÄÄĽ ÔÍÍ;

Any other value draws the panel without a border.

Although the boxes drawn by PANEL resemble popup windows, you cannot
restore the screen contents overwritten by a box once it has been drawn.
See the POPUP and SHUTUP routines, however, for a full windowing
system which does preserve the display.


REVINPUT

Accepts user input in a Reverse Video entry panel, all the usual editing
keys are supported and entry may be terminated by either a carriage-return
or one of several special function keys (see below).

DECLARE FUNCTION RevInput$ (Max%, Default$, Legal$, Ctx%, Topic$,_
Mask%, HotKey%)

Max% = maximum number of characters which can be accepted.
Visible% = maximum number of characters which are visible on the
display. If non-zero and less than Max%, this is the
actual size of the data-entry panel.
Note: the data-entry panel will scroll, if necessary, to
ensure that the current character position is always
visible.
Default$ = default string which can be accepted by just pressing
the key.
Ctx% = set TRUE if context-sensitive help is available, in
which case ...
Legal$ = a string of legal characters which are acceptable for
input. If a null string is passed then all printable
characters will be accepted.
Topic$ = name of the HELP Topic file to display whenever the
key is pressed.
Mask% = if TRUE (non-zero) prevents the characters entered from
being echoed to the display. Instead an asterisk (*) is
displayed for each character position although the entry
string itself is unaffected. Use this for passwords.
HotKey% = If entry is terminated by anything other than the
key, this variable will contain an explanatory
return code ..

Return Codes: 1 = abort entry returning a null string
2 = repeat previous entry for this field
3 = pressed, move to previous field
4 = pressed, move to next field
5 = pressed, move to top of screen
6 = pressed, move to end of screen
7 = A hotkey was supplied and used. The calling
program takes appropriate action.

You can specify any key as the hotkey by setting your
own value in HotKey% before calling REVINPUT. This
number can either be the ASCII code of any standard
key or the SCAN code (as a negative value) of one of
the function keys. Set HotKey% to zero to turn off
keyboard trapping (except for keys 1-6 above).

Editing Keys: = Move cursor one character to the left
= Move cursor one character to the right
= Move cursor to first character of field
= Move cursor to last character of field
= Clear from current cursor position to
the end of the entry field.
= Toggle between Insert and Overtype modes
= Delete character under the cursor.
= Replace character under cursor with a
blank space and move cursor one character
to the left.
= pop up on-line HELP screen.

REVINPUT is designed to be used as part of a full-screen data-entry
system. Your program can examine the return code to determine whether the
operator wishes to terminate entry or move forwards or backwards between
entry fields.

See also the DATEINPUT function for a keyboard routine specially designed
to ask the operator for a date!!!!


ROOTNAME

Extracts the root filename from a full directory pathname.

DECLARE FUNCTION RootName$ (Path$, Extension%)

Path$ the full directory pathname of the file in question. This
string can include the drive letter followed by a colon.

Extension% If TRUE (non-zero) the returned filename will include the
filename extension (if any). If FALSE (zero) the extension
part is trimmed off.


ROUND

Rounds a double-precision number to the number of decimal places required
and returns it as a string.

DECLARE FUNCTION Round$ (Number#, Places%)


SALUTE

DECLARE FUNCTION Salute$ (Original$)

This function strips all but the first and last words from a string
and capitalises the first letter of each remaining word. This produces
a string suitable for use as the salutation of a letter.


SCREENMODE

This function calls ROM-BIOS to check the current video mode and then
converts the returned value to the equivalent QuickBASIC SCREEN number.
It can detect the Hercules 720 x 348 graphics mode (SCREEN 3) and the new
Olivetti 640 x 400 mode (SCREEN 4) as well as the Tandy 1000 and PCjr CGA
modes (SCREENs 5 & 6) which are not supported by QuickBASIC. Other
unsupported graphics modes return a value of -1.

No calling parameters are required.

DECLARE FUNCTION ScreenMode% ()


SETFLAG

This routine is used to set one of the sixteen system flags to a value of
between 0 and 255. These flags are situated in the Intra-Application
Communications area, an area reserved by DOS for user programs to signal
to each other. FLAG% is the flag number (1-16), VALUE% is the value you
want to set.

DECLARE SUB SetFlag (Flag%, Setting%)

You can read the current setting of a particular IAC flag byte with the
GETFLAG function.


SORTFILE

expects the user to supply the name of the file to be sorted. The file,
itself, must be fixed length and its name can include a drive letter and
directory pathname. The logical record length of the file must also be
supplied, along with the start position and length of the field which the
file is to be sorted on.

The procedure returns with Done% set to -1 (logical TRUE), if the sort
completed successfully, or to zero (logical FALSE) if an error occurred.

DECLARE SUB SortFile (PathName$, OffSet%, FieldLen%, RecordLen%, Done%)

The program first checks the size of the file and the amount of free disk
space to see if the it can be sorted in memory, this requires space for
two copies of the file on disk. If it is too large, the file is sorted in
place so that no extra disk space is required. Using this method, which is
far slower, the file may be of any size up to 4 Gigabytes.

Note: If, when sorting in place on disk, SORTFILE detects that there
is a Ramdisk installed with enough free space to hold the file
that is being sorted, the program will copy and sort the file
there. This is much faster than a conventional disk sort, but
still not as fast as sorting directly in memory.

Programs calling this routine must have at least two unused file buffers
available (i.e. no more than thirteen files must be already open).


SPLITNAME

Parses a string containing the full or postal name of a person and
extracts the TITLE, INITIALS and SURNAME from it.

DECLARE SUB SplitName (Source$, Title$, Initial$, SurName$)

Most commonly used titles (eg MR, MRS, MISS, MS) are correctly
identified and seperated out.


STRIPQUOTES

Strips quotation marks and commas from a string which is to be
written to a comma-delimited ASCII file.

DECLARE FUNCTION StripQuote$ (Source$)

All double quote characters (") found in SOURCE$ are replaced
with single quotes (') and all commas replaced by blank spaces.
The length of the string is unchanged.


UNPAD

Removes multiple spaces from a string, making sure that no word
in a string of text has more than one blank space between it.

DECLARE FUNCTION UnPad$ (Text$, Length%)

Text$ the string of text to be processed.

Length% on return, holds the length of the string after
processing.

Leading and trailing spaces are also trimmed.


VERMENU

Displays and operates a pulldown menu, allowing the user to select from
the list of options displayed in the menu window.

DECLARE SUB VerMenu (Row%, Col%, Attr%, Bdr%, Opts%, Title$, Menu$(),_
Choice%, Nxt%, Bar%, Ctx%, Tpc$, Mouse%, HotKeys%)

Expects: Row%, Col% screen co-ordinates of top-left corner of the
window containing the menu.
Attr% display attribute given to menu window.
Bdr% Border style (1 - 8, 0 = no border). see the
WINDOWS documentation for a list of styles.
Opts% Number of options provided by menu.
Title$ Title for the menu, if null string then no
title is displayed.
Menu$() Text for options list.
MENU$(0) should contain a list of Hotkey
characters, one for each option. Insert a space
at the appropriate position if an option is to
be disabled. A hash character '#' in Menu$(0)
will replace the option at that position with
a horizontal line seperator.
In the remaining option strings an ampersand '&'
indicates that the next character is the Hotkey
to be highlighted for that option. The Hotkey
character should be the same as the one in the
appropriate position of Menu$(0)
Ctx% If set, this indicates that context-sensitive
help is available, in which case ...
Tpc$ The root name of the Topic file to be displayed
if the user presses for help. The current
menu number and selection number are appended to
this to produce the actual filename, eg where:

Tpc$ = "CONFIG" Bar% = 2 Choice% = 5

HELPMATE (see TOOLBOX.DOC) looks for a Topic
file named CONFIG25.HLP.

(Note that Bar% is automatically set if you are
using this function in conjunction with BARMENU.
if not, Bar% defaults to zero and HELMATE expects
CONFIG05.HLP to be the appropriate TOPIC file.)

Mouse% If set, this flag indicates that a mouse is
installed and can be used to make selections.
HotKeys% If set, this flag allows hotkeys to go directly
to a selection without the user having to press
as well.

Returns: Choice% Number of selection made by user. If zero then
the user pressed to abort without making
a selection.
Nxt% Set TRUE if the user pressed the left or right
arrow key to move sideways to another menu, in
which case ....
Bar% is incremented or decremented accordingly.

The BARMENU procedure provides a similarly featured menu which is
orientated horizontally.

See the source code for DEMON.BAS, the Toolbox demonstration program, for
an example of VERMENU (and BARMENU) in use.


VIDEOMODE

Checks the video system capabilities of the host computer.

DECLARE SUB VideoMode (Colour%, MaxRes%, VideoRam%)

This function calls ROM-BIOS to check the type of display adaptor which is
installed in the host system. Three variables are supplied which, on
return, provide the following information:

COLOUR% -1 = Colour adaptor Indicates the presence of a colour
0 = Monochrome monitor in EGA systems. Returns -1
for CGA, even if a mono monitor is
bring used.
MAXRES% highest SCREEN Highest resolution graphics screen
resolution which can be set. Is equivalent to
QuickBASIC SCREEN numbers. MDA can
only use SCREEN 0, CGA 0, 1 and 2
N.B. MaxRes% = 10 indicates an EGA
with mono monitor. This means that
SCREEN 9 can NOT be used.
VIDEORAM% in kilobytes Amount of dedicated display memory
installed.
MDA = 4K, CGA = 16K, EGA = 64-256K


EXTRA ROUTINES FOR QB4

The following functions and procedures are only included in the version of
the Toolbox intended for QuickBASIC 4.x and BASIC 6. They are omitted from
the later version because the Extended QuickBASIC language provided with
the BASIC 7 Professional Development System includes new statements and
functions that render them unneccessary.


CHANGEDIR

This procedure changes the current directory to the one specified by the
pathname supplied. If a drive letter is included in the argument, the
routine also changes the current drive.

DECLARE SUB ChangeDir (PathName$)

Microsoft have now added CHDIR and CHDRIVE statements to QBX, the new
Extended QuickBASIC supplied with BASIC 7. Since these statements make
CHANGEDIR redundant, it is not provided with the BASIC 7 Toolbox.


WAITASEC

System-independent pause for a specified number of seconds. The delay will
still be the same, whether you have an original IBM-PC or an AT with the
latest Intel i486 processor running at 33MHz.

DECLARE SUB WaitaSec (Seconds!)

This is an alternative to the SLEEP statement, for people who still use
QuickBASIC 4.0