Black Box 4/BlackBox.cdr/progbas/qb4tb520.arj/MIXED.DOC

Text File | 1991-08-24 | 25.6 KB | 642 lines

            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 <F1> for help. The current selection number
                is appended to this to produce the actual filename.
Mouse%      =   If set, this flag indicates that a mouse is installed
                and can be used to make selections.

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

On completion the procedure returns with the following variable set:

Bar%        =   Number of selection made by user. If zero then the
                <Escape> 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$)


BITRESET

Clears the specified bit (0-15) of the integer number supplied.

DECLARE SUB BitReSet (Number%, Bit%)


BITSET

Sets the specified bit (0-15) in the integer number supplied to 1.

DECLARE SUB BitSet (Number%, Bit%)


BITTEST

Returns logical TRUE (-1) if the bit (0-15) of Number% is set and FALSE
(zero) if the bit is clear.

DECLARE FUNCTION BitTest% (Number%, Bit%)


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 <Escape>, 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 <Escape> 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 <Enter> key.
Context%    =  set TRUE if context-sensitive help is available, in
               which case ...
Topic$      =  name of the HELP Topic file to display whenever the
               <F1> key is pressed.
HotKey%     =  If entry is terminated by anything other than the
               <Enter> key, this variable will contain an explanatory
               return code ..

Return Codes:   1  =  <Escape> abort entry returning a null string
                2  =  <F2>     repeat previous entry for this field
                3  =  <Up Arr> pressed, move to previous field
                4  =  <Dn Arr> pressed, move to next field
                5  =  <Pg Up>  pressed, move to top of screen
                6  =  <Pg Dn>  pressed, move to end of screen

Editing Keys:   <L.Arrow>   =  Move cursor one character to the left
                <R.Arrow>   =  Move cursor one character to the right
                <Home>      =  Move cursor to first character of field
                <End>       =  Move cursor to last character of field
                <Ctrl End>  =  Clear from current cursor position to
                               the end of the entry field.
                <BackSpace> =  Replace character under cursor with a
                               blank space and move cursor one character
                               to the left.
                <F1>        =  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$ ()


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 <ESC> 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
<Escape> 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

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.

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.


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.
Default$     =  default string which can be accepted by just pressing
                the <Enter> 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
                <F1> 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
                <Enter> key, this variable will contain an explanatory
                return code ..

Return Codes:   1  =  <Escape> abort entry returning a null string
                2  =  <F2>     repeat previous entry for this field
                3  =  <Up Arr> pressed, move to previous field
                4  =  <Dn Arr> pressed, move to next field
                5  =  <Pg Up>  pressed, move to top of screen
                6  =  <Pg Dn>  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:   <L.Arrow>   =  Move cursor one character to the left
                <R.Arrow>   =  Move cursor one character to the right
                <Home>      =  Move cursor to first character of field
                <End>       =  Move cursor to last character of field
                <Ctrl End>  =  Clear from current cursor position to
                               the end of the entry field.
                <Insert>    =  Toggle between Insert and Overtype modes
                <Delete>    =  Delete character under the cursor.
                <BackSpace> =  Replace character under cursor with a
                               blank space and move cursor one character
                               to the left.
                <F1>        =  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!!!!


ROUND

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

DECLARE FUNCTION Round$ (Number#, Places%)


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.


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%, Topic$, Mouse%)

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 key characters, one for each option.
                        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.
          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 <F1> for help. The current
                        selection number is appended to this to produce
                        the actual filename.
          Mouse%        If set, this flag indicates that a mouse is
                        installed and can be used to make selections.

Returns:  Choice%       Number of selection made by user. If zero then
                        the user pressed <ESC> 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