Programmer 7500/MAX_PROGRAMMERS.iso/INFO/BASIC/GLIB14.ZIP/GLIB14.DOC

Text File | 1988-02-06 | 101.3 KB | 2,524 lines

                            GLIB version 1.40
                         Released: February 6,1988
                        Copr InfoSoft, 1986-1987, 1988


    The files that should be included on this disk or .ARC archive are:
    GLIB14.NEW    - Overview of new stuff in GLIB 1.4.
    GLIB14.DOC    - This documentation.
    GLIB14.QRF    - A quick reference guide to using the routines.
    GLIBDEMO.BAS  - A QB demo of some of the routines.
    GLIB14.QLB    - The same routines for use with QB4 environment.
    DIR.SUB       - Interface to replicate DOS DIR command in QB4.
    EMP.DAT       - Sample data file for FED-DEMO.BAS
    CHGFLD.SUB    - Subroutine handler for FED (example).
    FED-DEMO.BAS  - Demo of FED, text input handler.
    FED.DOC       - Documentation for care and feeding of the Field Editor.
    GLIB14.INC    - Declarations for GLIB 1.4
    GQLB14.MAC    - Macro responce file for LINK to make GLIB14.QLB
    MAILER        - Quick Mailer for registering.
    ANNOUNCE.TXT  - Major annoucement on GLIB


    Note: Due to the popularity of QB4, user libraries for prior versions
          of QB are not supplied, but are available on request.


    License, Terms and Use:
    =======================
       Under no circumstances may these routines be distributed individually
    or without the accompanying documentation, which is an integral part of
    the package, nor may the documentation be altered in anyway.  This
    includes, but is not limited to distributing, GLIB14.QLB for use in
    executing applications compiled to BRUN format.

       Under no circumstances may the routines in the GLIB14 package,
    source, object files, libraries or documentation be distributed by or
    otherwise become a part of, or affiliated with any group or organization
    involved in the distribution of what is generally been come to be known
    as SHAREWARE for disk or distribution fees, or for fees of any sort
    without my express WRITTEN consent.  This includes supplying the
    routines, library and or documentation for so-called disk fees.

       Finally, as the author, I make no claims that the routines herein
    will fit your needs, simply that in all testing and prior use that they
    worked for me and that you may find them interesting and helpful in your
    programming.  Any liability for the use, misuse or inability to use the
    GLIB14 routines or libraries, is solely the users.


    1.   Compatibility
       The routines used in GLIB14 are written mostly in assembler and
    assembled under MASM 5.0.  The few BASIC based routines that there are,
    were written under QuikBASIC 4.0.
       GLIB14 will almost certainly choke under earlier versions
    of QB as I have made it a point to take advantage of functions and
    structures new and unique to QB 4.0 where it makes sence and was
    prudent.  I would be amazed if more than a few worked under the BASCOM
    BASIC compiler.



        DO NOT attempt to combine older QB3 routines with QB4 routines into
    a QB4 compiled program or library.  ASM based routines require signif-
    icant conversion for use under QB4.  Linking QB3 and QB4 BASIC based
    routiens will require that both runtime modules be used, BCOM/BRUN30
    and BCOM/BRUN40 - which WILL yield certain disaster.


    2.    Support
       As long as it exists, I will support and entertain questions
    regarding QB and/or GLIB  via the QuickBASIC conference on
    The Information Booth, [phone], 1200 - 19200 bps, 24 hrs.
       If you have a problem or question on GLIB, PLEASE be prepared to
    supply some sort of source code to demonstate your problem.  I am more
    than a little interested in any GLIB or QB bugs that you might find,
    but PLEASE do not waste my time with general, vague inquiries without
    supporting source examples.



    3.   License
       You are granted free and unlimited use of any and all routines in
    GLIB14 that you may find of value.  Furthermore, you are free to pass
    along the BBS distribution files (listed at the start of this document)
    as long as they are passed along as a whole according to the guidlines
    listed above.
       No one is granted any permission to share or pass along the BCOM
    library or any BCOM object files.



    4.    Purchase
       As distributed, GLIB14 documentation, the demo and the environment
    library provide you with everything you need to call and execute GLIB14
    routines from within the editor/environment.  Furthermore, as described
    above you are given unlimited rights for such use.  This provides an
    ample forum for purposes of sampling, testing and evaluation and allows
    unlimited latitude in terms of personal use or as a tutorial regarding
    some of the more advanced features in today's QuickBASIC.  If any of
    these are your intention, then the files included with this
    documentation provide everything you need, and you are free to use them
    in that format.

       However, you might find some of the routines of value and want to
    incorporate them into a standalone (.EXE) application.  In this case,
    the library of routines and permission to use them in such applications
    is able to be purchased as described below.

       It is my contention that this is the best of all worlds.  You get
    unlimited personal and/or evaluation use.  If you find it of value, the
    BCOM library can be purchased.  If GLIB does NOT fit your needs, then
    you are 'out' nothing (not even the time to download the .LIB) and do
    not need the .LIB file.



       To get the latest version of GLIB14 as well as the standalone
    library (.LIB), do any of the following:

    a. Fill out the enclosed mailer, with $20 and mail it to the address
       below and I will mail back a diskette containing documentation, and
       environment library(s) for release 1.4.

    b. Upgrades can be had in 2 ways:
       Fill out the mailer, indicating an upgrade and send it back
       indicating that you are upgrading with $10.00 and get a diskette
       back in the mail.




    Mailing Address:
                                 InfoSoft
                               PO Box 782057
                                Wichita, Ks
                                       67278-2057


       Upgrading:  Upgrades are avialable to anyone who has purchased ANY
    previous version of GLIB.  That is, if you purchased 1.0, but not 1.1 or
    1.2, you are still able to get 1.3 at the upgrade price rather than as a
    new purchase.  So, if any given release does not have anything that you
    have a specific use for, there is no need for you to upgrade simply to
    keep your upgrade path open.





    I.  GLIB14 - Introduction


       GLIB14 is a set of routines that are callable from either
    QB3 or QB4.  Some, such as ERRMSG, more resemble sub-programs
    than sub-routines.  To say this is not to overstate their value, but to
    point out that, in general, they perform or can perform multiple
    functions or entire routines.

       Most of the routines are assembler based, but where it makes more
    sence, they are in QB.  In terms of speed and such, assembler based is
    undoubtedly faster (though I doubt that the amount by which it is faster
    is always noticeable), QB routines on the otherhand can be a bit more
    useful: the most noticable difference being that QB subroutines can
    alter string lengths while assembler cannot.  The downside is that QB
    routines are a bit bigger, but I still appreciate having them right on
    hand and not having to type them in numerous times.



    II.  Calling Conventions
      If you are not familiar with calling library routines from QB, you
    are advised to STUDY this in the QB books, as it is an important aspect
    of calling sub programs.

    Brief Rules:
    A.  The passed parameters shown do not need to be used literally as is.
        That is, if a routine is documented as:
        CALL myroutine(StringParm$, IntegerParm%)
        The following convention will work just as well:
        CALL myroutine(parm1$, parm2%)
        The following will not (because the variable data types are
        reversed):
        CALL myroutine(StringParm%, IntegerParm$)

       What this is saying is that called subroutine parameters are only
    POSITIONAL, but they can have any name you choose ("IntegerParm%" vs
    "parm2%"), and as long as the TYPE is correct (integer versus string
    variables, versus double precision etc), and as long as the passed
    arguments are initialized correctly.



    B.  Unless otherwise noted, subroutines require non-string arguments to
        be INTEGERS.  This means that either a DEFINT a-z statements is re-
        quired early on in your program, or numeric arguments must be im-
        plicitly designated as integers, (the "%") integer declaration used.



    C.  Aside from the right TYPE of argument or parameter being passed,
        and the use of integers, make sure you pass the right NUMBER of
        arguments.  If a program requires you to pass 7 arguments and
        either as a typo or because you only use 6, you miss one within the
        parentheses, then as they say, unpredictable results may occur.




    D. In most cases, the examples shown will reference parameters as
       variables. ie:  CALL subr(x%, y%, z$); where x, y and z$ are set to
       certain values to get specific results from the routine.  However in
       many cases, you can pass arguments directly.  ie:
       CALL subr(1, 4, "String").
       The times when you CANNOT do such direct passing is when the
       subroutine is going to modify or return one of the arguments passed.

       Some routines will change one of the arguments to indicate an error
       or a level of success.   Those arguments do, MUST be passed as a
       variable.  For example, if "subr" above uses x, y and z$ to
       specify what you want it to do and y returns a level of success or
       error situation, it would have to be passed as a variable:
       CALL subr(1, y%, "String")


    E.  FUNCTIONS

         There is a reasonably simple way of structuring ASM subroutines
       to perform the same way that one of your BASIC functions will, or
       the same way that INSTR does.  In many cases this is highly
       productive for us because we can keep the number of parameters we
       need to pass and simply return error conditions in the NAME of the
       function.
          As of GLIB 1.4, we have implemented this feature.  In all but a
       very few cases this FUNCTION return only indicates some sort of
       error condition.

               WHAT you need to do to use ASM FUNCTIONS:
         The absolute simplest way is to merely $INCLUDE the enclosed
       GLIB14.INC file and let it do the work.  This must be done BEFORE
       any executing statements like CLEAR, or DEFINT (DEFLNG etc).

          To do it by hand, refer to the syntax in the QB book, but keep in
       mind that since the DECLARE's are BEFORE any DEFINT statement, that
       each argument AS WELL AS THE FUNCTION NAME must have the integer
       type identifier or else they will default to BASIC's float.

    RIGHT:   DECLARE FUNCTION dayofyr%
    WRONG:   DECLARE FUNCTION lastdrv             ' all FUNCTIONS use integer

    RIGHT:   DECLARE FUNCTION feof%(fhandle%)
    WRONG:   DECLARE FUNCTION funiq%(fil$, mode, fhandle%)
              ' all arguments/parameters are NOT integers!

       The rule of thumb is that if everything has a $ or a % next to it, it
       will work alright.

       We also use a combo of FUNCTIONS and SUBS.  In the example above for
       FUNIQ - we pass a path and mode and FUNIQ will return a file handle
       to us OR a error code in the function name if some went awry.



       The obvious benefit to us in our BASIC code is that if we have a
       FUNCTION named EXIST (which we do) the code becomes much more
       readable:

       FUNCTION:
       IF NOT exist("GLIBDEMO.BAS") THEN END

       Subroutine:
       CALL exist("GLIBDEMO.BAS", ReturnCode)
       IF NOT ReturnCode THEN END



    III.    DOS File Functions:

       With the release of GLIB 1.4, we have implemented several important
    DOS file functions to open, write to, close files as well as create
    truly unique scratch files and set the file pointer to the End Of a
    File.   The benefit of DOS File Functions over BASIC's native access
    methods is that is that rather than causing a runtime error, we can get
    a return code back from DOS.  Additionally, there are some benefits
    inherent to the functions themselves (see FUNIQ).  In interfacing to
    other languages like C and ASM, we can pass an already open DOS file
    handle they can use, which cannot be done with the native commands.


       Aside from avoiding runtime errors, the advantage of these functions
    is easier and error free access to files by other languages.  For
    example, the routine LCOUNT counts the number of lines in a text file
    (carriage returns actually).  If you were to have the file OPEN in BASIC
    and attemptted to open, read, then close the file in assembler, the
    file could be damaged depending on the mode it is open in and how much
    is data is buffered by BASIC and not yet to disk.  If LCOUNT opened it
    itself and then closed it upon completion, would the BASIC buffered
    data be put to disk?
       In its actual implementation, LCOUNT is passed a file handle opened
    via FOPEN.  LCOUNT neither opens nor closes the file, just acts upon the
    file handle you pass it so that nothing unwittingly happens to the file.
    Buffered, unwritten data from a BASIC file mode is still a question, but
    you maintain control over that via error returns from FOPEN and LCOUNT,
    and LCOUNT does not even attempt to open or close the subject file.


       With the use of DOS File Function come new terms: mode, access
    rights, attributes, file handles and etc.  Here is a brief overview:

    FILENAME:  The name is any legal DOS filename (see VFNAME), there is
         no need to tack on a NUL ( CHR$(0) ) to make it ASCIIZ, InfoSoft's
         routines are intelligent enough to do it themselves.

    FILE HANDLE:  The DOS File Functions return or deal with a file handle
         which is just a 16 bit token identifier used by DOS, ASM and C
         that  identifies a particular file and access mode to the
         operating system.   In normal use, the first file handle to be
         issued is 5.  This is NOT the same as attempting to OPEN fil$ FOR
         OUTPUT AS #5.  The concept is the same but the BASIC file numbers
         mean nothing to DOS, only to BASIC.  Simply put, the BASIC file
         numbers are handles of handles issued by DOS.



         The first 5 file handles are reserved for what is called the
         standard devices, these are:
           0 - STDIN (keyboard)
           1 - STDOUT (monitor)
           2 - STERR (monitor again)
           3 - STDAUX (first serial device)
           4 - STDPRN (printer)
         Given that, DOS will issue 5 as the first available handle.  After
         you FOPEN or FCREAT the file with handle 5 it remains open and
         active until you FCLOSE it, that is, it is not affected by BASIC's
         native CLOSE statement.

    SHARE MODE: The mode parameter allows for control over file sharing
         when the program is to be used in a Network or multitasking
         environment.  For simplicity, for normal mode set the mode
         parameter to 0, for multitasking, set it to one (1).  In order to
         be able to actually take advantage of the sharing rights, the DOS
         SHARE.EXE program must be loaded and resident.

    ACCESS MODE: The mode refers to whether the file is to be opened with
         read, write or read/write access.  In order to keep this simple,
         for the time being, FOPEN automatically opens all files to Read and
         Write access.  This is to keep it simple and to keep the nunmber of
         parameters managable.


    FILE ATTRIBUTES:  Do not get this read/write access confused with file
         attributes.  The access mode refers to how a file is opened, with
         what rights while file attributes refers to the characteristics of
         the physical disk file.  SETFATTR and GETFATTR allow you complete
         access to get or set or reset file attributes of ANY file on the
         disk - so be careful.  Additionally, to FCREAT a file, you must
         specify what attributes are to be used.  File Attributes are:
            00  -  Normal: like most files on disk
            01  -  Read Only: may be opened for read, but not writing
            02  -  Hidden: does not show in DOS 'dir' command
            04  -  System: used for the hidden system files
            32  -  Archive: used to flag files that need to be backed up.

         To combine attributes, add up the values: a hidden, system,
         read-only file has an attribute of 7 (1+2+4).

    ERROR CODES:  The File functions actually return 2 types of error
         indicator.  One reflects any DOS level error and the other attempts
         to catch and warn of operator error.   In the case of FOPEN, the
         file handle is returned as a parameter.  If an error occurs, that
         error is passed in the function name:

    IF fopen(fil$, mode%, fhandle%) THEN PRINT "Error!"

         This should do wonders for making code more readable.  All the File
         functions implemented work in a similar fashion: error codes are
         returned in the name to allow you to either assign the result or to
         evaluate it directly.  See "ASM FUNCTIONS"



         As a rule, -1 indicates some sort of parameter error that the
         called routine notices.  An example would be a nul string as a
         filename or an attempt to FCREAT a standard DOS handle (0-4).  This
         varies a little from routine to routine so be sure to check the
         documentation for each function.

         For the most part DOS uses the same error codes throughout the file
         functions, and since these routines all just pass back any such
         error report, you could write a single SELECT CASE construct to
         sort out the error and provide user feedback or attempt to correct
         the error for ALL of the DOS File Functions provided.

    DOS Error Codes:
         1 - Invalid function (unlikely you will get this one)
         2 - File Not Found
         3 - Path not found (can also mean that an indicated drive is
             invalid or not found)
         4 - No Handle Available.  BASIC reports such a condition as
             "Too Many Files".  The config.sys FILES= statement may need
             to be modified to correct this or simply FCLOSE and CLOSE a few
             file handles.  By default DOS allows 12 files open at a time,
             and 5 are always open as standard handles.
         5 - Access denied.  An attempt to open a file for Writing that is
             READ only or another node on a network has exclusive rights on.
         6 - Invalid Handle.  The handle passed is not OPEN, or not open in
             the right mode.
        18 - No more files - unlikely you will get this one.
        80 - File already exists.  Possible return by FUNIQ.



    III.  Classifications.
       Each routine description following is titled by a header with some
       general information about the routine:
       o  ROUTINE NAME (FUNCTIONS are so labeled).
       o  The TYPE indicates the type of function it is;
       o  The LEVEL is meant to designate the probability of the routine
          running on the less compatible clones.  QB level routines are
          written in QB and should run no problem, BIOS and DOS level
          routines are written in Assembler, thus it depends on the
          compatibility level of your skinjob (see BLADERUNNER) whether it
          will work ok or not.  Hardware level routines require clones of
          the highest compatibility to run correctly.



    IV.  Major QB bug(s)

    A.  NOTE WELL:
        There is a fairly well known bug in QB3 that creates non
    executing .EXE files when your program performs calls to assembler
    routines.  The work around is this:

    DO NOT compile your source from INSIDE the editor to make a .OBJ file.
    DO exit to DOS and make the .OBJ file from DOS:
    C>QB myprog /o;
    Then when you link it, the EXE file will run.

       By "fairly well known bug" I mean that most serious users know about
    it.  I have let MicroSoft know and provided 4 examples and they now
    understand what the problem is, but DO NOT expect a fix for it,
    because they are more intent on OS/2 and QB4 is now out.


    B.   Note Well also:
         A very similar bug appears to be present in QB4.  When you compile
    and LINK from inside the environment, QB4 has a nasty tendency to add
    the ENTIRE referenced library to your executable, NOT just the called
    routines.  (Glad the beta testers caught that).
         Further, odd things also happen when making QLB's from inside the
    editor.  The moral is to link, compile and create LIBs from DOS.



      GLIB 1.4 Index
      --------------
      BOXES ........... Outline one of 6 menu type boxes to the screen.
      CHRP ............ Sound the speaker in a CHiRP fashion.
      CLOFF / CLON .... Disengage-engage keyboard Caps Lock.
      CLRKBD .......... Clear keyboard buffer of type-ahead keys.
      CMDLINE ......... Parse the command line into a string array.
      CPUINFO ......... Returns very low level system info, CPU type etc.
      DATE ............ Returns current day, month, year and DOW as integers.
  **  DAYOFYR ......... Returns the current day of the year (1 - 366).
      DFRMAT .......... Date Formatting.
  **  DLIGHT .......... Trigger a floppy disk light on.
   *  DIR.............. Returns DOS directory in a string array.
      DLRFRMAT ........ Numeric string formatting to Dollar conventions.
      DLY ............. Delay for x number of seconds.
      DOSV............. Return DOS Version installed.
      DRVSPACE ........ Return total and free drive space.
      ERRMSG .......... Display temporary message with color, sound control.
      EXIST ........... Determines if a file exists on disk or not.
      EXTMEM .......... Return the amount of Extended (AT) memory installed.
      FADE ............ Screen fade or dissolve routine, maintains attributes.
  **  FCOPY ........... Copy a file, as quickly as DOS.
      FILCNT........... Returns the number of files in disk matching a mask.
      FED ............. BASIC text input routine.
  **  FEOF ............ Set file pointer to the end of a file.
  **  FCREAT .......... Creat a new file, returning a DOS File handle.
  **  FOPEN ........... Open a disk file, getting a DOS file handle.
  **  FUNIQ ........... Creste a unique/temporary file.
  **  FWRITE .......... WRite a string to s file opened with a DOS handle.
  **  GETCH ........... Allow input from predefined string.
      GETDSEG ......... Returns BASIC's DS (Data Segment)
  **  GET/SET FATTR ... Get, set or reset file attributes.
      GETSTACK ........ Returns the state of BASIC's Stack.
      GET/SET DRV ..... Get or set the default drive.
      GET/SET VERFY ... Get or set the system VERIFY state.
      GRAPH ........... Produce a Vertical or Horizontal graph from an array.
  **  INCR / DECR ..... Replicate TURBO BASIC functions
  **  INSON / INSOFF .. Toggle insert state on or off
      KBLOOP .......... Enter a blind loop until a key is pressed.
  **  LASTDRV ......... Return last logical drive on the system
  **  LCOUNT .......... Count the number of lines in a text file QUICKLY.
  **  LNAMEF .......... Swap names to last-name-first format.
      MDLY ............ Delay processing for a number of milliseconds.
  **  MCSRINC / MCSRDEC Decrement mouse cursor flag
  **  MCSRON / MCSROFF  Mouse cursor on or off.
  **  MGETXY .......... Get mouse cursor location
  **  MLONG /MNORM .... Set / reset mouse Mickey Factor.
  **  MPRESS .......... Get number of mouse button presses.
  **  MRELEASE ........ Get number of mouse button releases.
  **  MSETXY .......... Set mouse cursor location
  **  MSETXRNG / MSETYRNG: Define/limit mouse work area.
  **  MTYPE ........... Test for mouse existance, get number buttons
      NFRMAT .......... Extensive Numeric string formatting.
      NLOFF / NLON .... Disengage-engage Keyboard Num Lock
      PCASE ........... Convert string to proper case.





      GLIB 1.4 Index (con't)
      ----------------------

  **  PGETCH .......... GETCH with cenetered prompt.
      PINIT ........... Initialize the printer.
      PFILE ........... Send a disk file to printer.
      PRTSCRN ......... Print the current display on the printer.
      PSTAT ........... Return the printer status.
      QUIKPRT ......... Another implementation of BYTE's QPRINT routine.
      RAMFREE ......... Returns memory installed in the system.
  **  RINSTR .......... Returns LAST position of a char in a string
  **  READSCRN ........ Quickly read a string from the CRT at currect location
      RSTSCRN / SVSCRN. Restores a screen previously saved by SVSCRN
      U-,D- SCROLL .... Scroll a portion of the screen up or down.
      SCROLLER ........ Scroll the screen left or right.
      SCRLOFF / SCRLON. Set Scroll Lock Off.
      SCRNDUMP ........ Dump the current display to disk.
      SETERR .......... Sets DOS "ERRORLEVEL" code upon program termination.
      SINFO ........... Equipment info: RAM, parallel, serial, EGA and VGA.
  **  SYSTIME ......... Return system time as integers.
      TFRMAT .......... Time formatting
  **  VFNAME .......... Test a string to see if it is a valid filename.
  **  VIDOFF .......... Turn CRT off.
  **  VIDON ........... Turn CRT back on.
      WDW ............. Windowing subroutine with sound, color control.

      *  DIR is actually a facade for a FINDF and FNEXT Functions
     **  NEW with this release.



    Name: CHRP                 Type: MISC              Level: ASM

    This routine is used to sound the speaker in either a fast tone of
    ascending or descending pitch.  The same method is used in WDW to make
    the popping sound.  CHRP is provided to allow you to make a un-popping
    sound when removing a window.
    There are 2 modes in the CHRP routine:
    mode 1 = ascending frequecy (up)
         2 = descending frequency (down)

    Syntax:
    -------
    m=1
    CALL CHRP(m%)  ' will sound a "chirp" of ascending frequency as will:
    CALL CHRP(1)



    Name: CLON, CLOFF          Type: KEYBOARD          Level: BIOS

    Neither of these take an argument or pass a parameter.  They simply
    engage (CLON) or disengage (CLOFF) the Caps Lock key.

    CALL CLON
    CALL CLOFF



    Name: CLRKBD              Type: Misc               Level: BIOS

    Clear the keyboard buffer of any and all waiting keystrokes.  This is
    an effective way of eliminating type-ahead in critical portions of your
    program

    CALL clrkbd



    Name: CMDLINE              Type: STRING            Level: QB

    Read the command line into an array for return to calling program.
    Whatever is on the command line will be returned with all leading and
    trailing blanks removed.  Any delimiter that you instruct the user to
    specify WILL be included in each element of the array, though no special
    character is required other than a space.  That is,

    QBPROG /NC /DEF
    will return 2 items in the array, "/NC" and "/DEF".
    If so instructed, you could just as easily instruct the user to start
    the program with:  QBPROG NC DEF or QBPROG -NC -DEF
    It will be up to you to determine which, if any, delimiter is used, just
    remember, CMDLINE only parses the command line it does not strip
    "special" characters (other than blanks) from it.

       The string array ARG$ should be dimensioned to the MAXIMUM number
    of command line arguments that you expect or that your application
    has available or allows (in case ALL of them are called).



       Q simply tells the routine the offset in the array to start
    storing the different arguments ie q=4 would place the first retieved
    argument in ARG$(4).  This is to allow placement in a config array and
    to allow for OPTION BASE 0 and 1.  After the call, Q may or may not
    indicate the correct number of arguments passed, depending on your
    OPTION BASE setting.

    Syntax:
    -------
    DIM arg$(x) : q=1
    CALL cmdline(arg$(),q%)

    Q returns the number of elements in the array starting at position 1,
    and arg$() holds the command line parameters.




    Name: CPUINFO              Type: BIOS, Hardware    Level: Hardware

    This is a fairly comprehensive routine to determine just what is in the
    system.  A few people had asked for some routines to determine how
    fast a system is running, this is product of those requests.



    This routine returns several things:
    1) ID Code - This is the byte in low memory, that is supposed to help
                 identify the type or class of machine.  It is probably 90%
                 accurate (I have seen very cheap clones return pure garbage
                 regarding what type machine they are).
     The codes range from 249 to 255:
        255 - Original PC type          254 - Some Later PC's, original XT's
        253 - PCjr                      252 - 286 class, PS/2 Model 50 or 60
        251 - XT/286 type machine       250 - PS/2 Model 30
        249 - Convertible               248 - PS/2 Model 80


    The machine also contains a revison level code called the revision level
    to help distinguish the original 6 Mhz AT from the 8 and the Model 50.
    The revision level is not yet returned by GIZLIB, but will at some time
    in the future.  This revision level helps differentiate a Model 50 from
    a Model 60 from a AT.



    2) CPU type installed, NDP type:
       CPU returns the significant numbers in the central processor
    identification and NDP returns info on any numerical processor:
           Type      CPU parameter        Type       NDP parameter
           ----      -------------        ----       -------------
           8086           86              None            0
          NEC V30         30              8087            87
           8088           88              80287          287
          NEC V20         20              80387          387
           80186          186
           80188          188
           80286          286
           80386          386

    Syntax:
    -------
    idcode=0 : cpu=0 : ndp=0
    CALL cpuinfo(idcode%, cpu%, ndp%)



    Name: DATE                 Type: Time and Date     Level: BIOS

    Return the current system date information.  Day, month, year and day of
    the week (1 - 7) are returned as integers.  The day of the week itself
    is helpful, but the day, month and year can be immediately used in
    DFRMAT.

    Syntax:
    d=0 : m=0 : y=0 : w=0               ' be sure to do this
    CALL date(m, d, y, w)



    Name: DAYOFYR              Type: Misc             Level: ASM
    FUNCTION

      This simply returns the day of year as an integer.  It is accurate
    for dates of 01-01-1980 to 02-28-2100 (The year 2100 is a centenial skip
    leap year - every 400 years we skip a leap year).  This is a FUNCTION
    that works off the current system date, returning the day count in the
    FUNCTION name.

    Syntax:
    DECLARE FUNCTION dayofyr%
    .
    .
    todaycount =  dayofyr



    Name: DFRMAT               Type: String            Level: QB

       Allows for DATE formatting.  The routine will pass back a date
    string formatted, for you to do whatever with.  This is handy in
    formatting DOS/BASIC's sterile date format into something that has a
    more pleasing appearance on the screen.
       You pass it valid integers representing the day, month and year, and
    DFRMAT returns a string similar to "August 1, 1987".  You can pass
    integers culled from BASIC's DATE$, those from DATE or any integer
    represeting a vaild date.
       DFRMAT has a lower range of 1800 as the year, and any year passed
    that is lower than 1800 had 1900 added to it, making 87 as valid an
    argument as 1987.

    Syntax:
    m=8 : d=1 : yr=87
    CALL dfrmat(m, d, yr, nudate$)
    PRINT nudate$                   ' output is August 1, 1987

    Alternative:
    m=0 : d=0 : y=0 : w=0
    CALL date(m, d, y, w)
    CALL dfrmat(m, d, y, nudate$)



    Name: DIR                  Type: DOS / File        Level: DOS

    DIR is actually a facade for 2 separate routines called FIRSTF and
    NEXTF to get the first filename matching a mask, then each of the other
    files matching that mask.

    To use them individually:
    mask$="*.bas"               ' any legal DOS mask will work
    fil$=SPACE$(12)             ' IMPORTANT!
    CALL firstf(mask$, fil$)    ' gets 1, the first name

    FOR x=1 to MaxFileCount     ' Use FILCNT to determine MaxFileCount
       fil$=SPCAE$(12)
       CALL nextf(fil$)         ' no mask
    NEXT x


    I have provided a file called DIR.SUB that handles much of this and
    stores all the names found in an array.  To Use:
    CALL filcnt(mask$, quan)         ' get how many there are
    REDIM fil$(qaun)                 ' size array to fit

    CALL dir(mask$, fil$(1))         ' dir will fill it up with names.



    Name: DLIGHT               Type: System           Level: BIOS
    FUNCTION

       DLIGHT triggers the A: or B: drive light for the length of a 2
    sector disk read.  This is helpful in demo or training programs to
    add realism to the session.  It uses a BIOS level diskette service call
    and will return a FUNCTION error of -1 if you attempt to invoke it on
    a drive other than 0 or 1 (A: and B: respectively).  On the otherhand,
    the drive light will come on even if the drive is open without causing
    a "Drive Not Ready" error!

    Syntax:
    DECLARE FUNCTION dlight%(drive%)
    .
    .
    IF dlight(drv%) THEN
       PRINT "Hey, dummy - I said A: or B: !")
    END IF



    Name: DLRFRMAT             Type: String            Level: QB

    This allows you to read input from a user in an application, and format
    it in various ways to currency conventions.  Your options include
    allowing a "$" in front or not: if you allow it, DLRFRMAT will check to
    see if it is there and add it if it is not; if you do not want it, it
    will strip it off if it is entered.  You also are allowed to format it
    out to 2 or 3 decimals (tenths of a cent).  This is useful for pay rates
    in restaurants or sales people on commissions who will often get paid
    rates to the tenth of a cent.

    Parameters:

    nst$=String containing only numbers, "." or "$" to be formatted.

    Mode 0 - Return numeric string without leading "$", forcing the
             entry of a ".".   If an element of the string is a period,
             an error is generated.

    Mode 1 - Returns the numeric string with a leading "$" (does not matter
             if it is passed or not), and forces "." as an element.

    Use the 2 foloowing modes with caution (if ever since ASSUMING the
    decimal position could be dangerous, however restoring dollar values to
    correct format from a random file, these modes help TREMENDOUSLY):
    Mode 2 - Strips any "$" present in the string, and assumes that if no
             decimal point is passed that it is the last element.

    Mode 3 - Returns string with a leading "$", assumes that if no deciaml
             point is passed that it is the last element.

    For logistical reasons, you must make sure that the mode parameter
    passed matches the least dangerous format.  There is a big difference
    between "$1.23" and "$12.30" and "$123.00", so you have the choice of
    forcing DLRFRMAT to return an error if one character in the string is
    NOT a ".".  You may also disable the forced error and assume that if
    there is no ".", that one should be appended to  the end of the string:
    ie "$123" is assumed to be "$123.00" NOT "$1.23" in this mode.



    P is used to tell DLRFRMAT how many decimals to pad to:
         2 - pads "123." to "123.00"
         3 - pads "45.1" to "45.100"
         0 - automatic dollar decimal placement:
            "5" becomes ".05",
            "70" becomes ".70"
            "146" becomes "1.46"

    Syntax:
    -------
    m=1 : p=3
    INPUT "Enter your wage: ",nst$              'user keys '7.50'
    CALL dlrfrmat(nst$,m%,p%)
    wag$=nst$
    PRINT nst$                                  'output: $7.500



    Note that in the case of an error, nst$ will return an appropriate error
    message and m will indicate an error code.  This allows you to test the
    return numerically by comparing m to 0,1,2 or 3.  You can then send the
    error string to the screen or route the code to your own error handling.

    m=50  nst$="Programmer error invalid number of decimals" [p not set
               right to 2 or 3]
    m=99  nst$="Invalid cahracters in input!".  [The string passed
          had ASCII characters above 57 ("9")] *
    m=98  nst$="Invalid characters in input!"   [The string passed had
          ASCII characters below 48 ("0")]  *
    m=97  nst$="You must enter a decimal point!".  One decimal must be
          passed if modes 0 or 1 are used.

    *   In both of these cases, p points to the position in string of the
        errorroneous character. If p=4 then there is an error 4 places
        right of any "$".



    Name: DLY                  Type: Misc              Level: BIOS

    DLY will pause a given number of seconds to allow the user to read a
    display that you may have sent to the screen.

    Syntax:
    -------
    sec=5 :  CALL DLY(sec%)            '     or    CALL DLY(5)

    Either form will pause processing for 5 seconds.  DLY is assembler based
    so pass only integers,  2.6 will crash the system.  If passing
    by variable (the first example above), you must specify "sec" as an
    integer when calling DLY (or declare all variables as an integer with a
    DEFINT A-Z



    Name: DOSV                 Type: DOS               Level: DOS

    Returns the DOS Version the system is running under.  This returns a
    whole number rather than the major and minor version numbers that you
    might be familiar with.  On the other hand, the number returned must be
    divided by 100 to convert it to conventional terms.  That is, DOS 2.11
    will be returned as 211, where dividing by 100 will yeild the more
    conventional 2.11 version.



    Name: DRVSPACE             Type: Disk              Level: DOS

    Returns Total clusters, bytes per sector, available clusters, and
    sectors per cluster for the specified drive, allowing you to determine
    the overall drive space and/or free space.

    Parameters:
    a - drive number to poll, 1= A:, 2=B: etc; 0 = default.
        Returns sectors per cluster
    b - Returns available count of available clusters
    c - Returns bytes per sector
    d - Total clusters on drive

    Syntax:
    a=0        ' read default drive
    CALL drvspace(a%,b%,c%,d%)

    total#=CDBL(a%)*CDBL(c%)*CDBL(d%)
    free#=CDBL(a%)*CDBL(c%)*CDBL(b%)       'total#=CDBL(a%*c%d%) won't work



    Name: ERRMSG               Type: Video             Level: BIOS

    ERRMSG is a fairly complex, very useful sub program completely in
    assembler designed to flash a programmer defined message to the screen
    pause 2 secs, then restore the screen.  It can be used for more than
    just error messages, but since it restores the screen after the message
    display, it seems best suited to error messages.  You determine the
    line to use, the subroutine automatically centers the message.


    Parameters:
    msg$= Message to display
    lin = Line for message to display on
    attr = attribute to use (indicates foreground and background color
           in one variable).  Calculated by the formula:
           (BACKGROUND.COLOR * 16) + FOREGROUND.COLOR
    sfx = Sound effects.  0=none 1=low tone

    Syntax:
    msg$="You must enter a customer name!"
    lin=15 : attr=31 : sfx=2
    CALL errmsg(msg$, lin, attr, sfx)



    Output would be a low tone beep and high intensity white letters on a
    dark blue background.  The message is centered on line 15.  The abilty
    to choose the display line allows you to for instance, place the above
    message right over the entry area for the customer name.  After the
    error message is displayed, there is a 2 sec pause and the screen is
    restored.

    Note: NFRMAT and DLRFRMAT in case of errors, returns an error message
    suitable for use directly in ERRMSG.  For example DLRFRMAT returns an
    error status in the mode parameter AND a message designed for the end
    user in the string parameter.  Your code can determine an error status
    via the change in mode and without knowing (or caring) what the error
    is send the string message to the end user, then loop back to the data
    entry point.



    Name: EXIST                Type: Disk / File       Level: DOS
    FUNCTION

       This routine returns a zero value or if the given file DOES NOT
    exist, and a non zero value (-1 actually) if it does.  There is no need
    for you to ludicrously append a CHR$(0) to the filename, assembler is
    very capable of doing that.
        If you have scads of code that already calls a file exist test that
    DOES add the null to the end of the filename prior to the call, you need
    not change it, since the first null marks the EOS to the assembler
    routine.

    Syntax:
    DECALRE FUNCTION exist%(fil$)
    IF exist("foo.bar") THEN PRINT fil$;" already exists! Overwrite?"



    Name: EXTMEM               Type: Misc              Level: DOS

    Returns the amount of extended, or AT memory, installed in a 286 based
    machine.  This only works on AT's or AT clones.

    mem=0 : CALL extmem(mem%)
    PRINT "AT has ";mem;" of extended memory installed."



    Name: FADE                 Type: Video             Level: BIOS

    This is an interesting alternative to CLS.  It quickly reads the
    character at each location on the screen and decrements the ASCII value
    of it until it reaches 32 (space).  The attribute (color) remains the
    same during and after the FADE.

    Syntax:
    CALL fade





    Name: FCLOSE               Type: Disk             Level: DOS
    FUNCTION

      As expected FCLOSE performs the opposite of FOPEN, close out a file
    handle open via FOPEN.  FCLOSE does some positive error checking to
    make sure that you do not attempt to close one of the standard DOS file
    handles (like the keyboard, monitor etc) and will return a error code of
    6 - Invalid File handle.

    See also FOPEN FUNIQ, FCREAT, FEOF, DOS File Functions (preceeding
    the reference section).

    Syntax:
    DECLARE FUNCTION fclose%(fhandle)
    .
    .
    result = fclose(fhandle)
    IF result THEN GOSUB error.control




    Name: FCREAT               Type: Disk             Level: DOS
    FUNCTION

      FCREAT is similar to FOPEN except that instead of opening an existing
    file, we are CREATING a NEW file.  As with FOPEN, and all the DOS File
    Functions, error codes returned in the BASIC FUNCTION format and are:
    -1    Null string passed
     3    Path not found
     4    No handle available ("Too many files")
     5    Access denied
    Note: You are encouraged to use EXIST first to see if the file already
    exists, executing FCREAT on an existing file truncates it to 0 bytes.

    Syntax:
    DECLARE FUNCTION fcreat%(fil$, attrib%, fhandle%)
    .
    .
    fil$="mainprg.sys": attrib=0
    IF fcreat(fil$, attrib, fhandle)=0 THEN
       PRINT "New file, ";fil$;" successfully created!"
    ELSE
       GOSUB whats.going.on
    END IF




    Name: FCOPY                Type: Disk/File        Level: DOS
    FUNCTION

      This function copys a disk file using an internal buffer, allowing it
    to perform about as fast as the DOS COPY command.  You pass it a source
    and destination string (paths / drives are ok).  The FUNCTION returns
    a variety of error conditions:
    -1 = Null string passed as source or dest.
     2 = File Not Found
     3 = Path not Found
     4 = No Handle ("Too Many Files")
     5 = Access Denied

       Syntax:
    DECLARE FUNCTION fcopy%(source$, dest$)
    .
    .
    result = fcopy("GLIB140.ARC","\GOODSTUFF\SAVE\GLIB140.ARC"
    IF result THEN PRINT "Oops!  Error - Check parameters!"




    Name: FED                  Type: String, I/O       Level: QB

    This is a very comprehensive text input routine that allows you
    extensive control over user input.  It too, is CALLed to exert control
    over the user's input, recognizing all cursor keys and most function
    keys.

    There are several things that sets this text input routine apart from
    ALL others you may see and be tempted to try out:
    1 - It is self contained and standalone.  It depends on NO external
        routines from this library or others.
    2 - The function keys are completely soft coded.  Hitting one exits the
        routine and returns control to you but exerts no editting control
        on the text such as clearing, tabbing etc.  This allows that the
        function keys can be used for a WIDE variety of purposes in ALL
        your application such as paging thru records in a database, Help
        and so forth.  (See FED-DEMO)
    3 - Requires no special compile switches even though it recognizes
        cursor and function keys.
    4 - Sensible configuration.  Thru the use of a COMMON block (clearly
        exemplified in the demo), you have COMPLETE control over colors,
        sound etc without having to explicitlty set and pass formal
        parameters for each call.  Furthermore, as a /block/, it does not
        monopolize all the COMMON space, and requires a paltry
        (20 + LEN(num$) ) bytes of COMMON DGROUP memory.
    5 - The comprehensive FED-DEMO not only clearly shows how to use it
        with a variety of other GLIB routines, but also shows a few
        intricasies of using FED with QB4 data structures.

                      DO NOT be misled by others,
                         FED, Field EDitor,
                  is the one they are impersonating.

    Complete documentation and use is in FED.DOC.



    Name: FEOF                 Type: Disk             Level: DOS
    FUNCTION

       Sets the file pointer to the end of a file opened via FOPEN.  This
    actually sets the pointer to ONE BYTE less than the end of the file.
    This is to be sure that subsequent FWRITE funtions overwrite the hard
    EOF marker (ASCII 26) left by some text editors.  Additionally, FEOF
    checks for invalid handles as well as the 4 standard DOS handles and
    aborts to return an error code of 6 - Invalid handle.

    Syntax:
    DECLARE FUNCTION feof%(fhandle%)
    .
    .
    IF fopen("longtext.fil", 0, fhandle) THEN
       GOTO start.new.file
    ELSE
       j= feof(fhandle)
       IF j THEN GOSUB weird.error
       GOTO append.to.text
    END IF



    Name: FOPEN                Type: Disk             Level: DOS
    FUNCTION

      FOPEN is a standard DOS function to open a file via a file handle.
    FOPEN requires a 'mode' be passed, 1 = multitasking or networking,
    0 = normal.  There is a way to set access rights (read, write,
    read/write) that also may be implemented later.  FOPEN should not be
    used to open a device such as a printer, but DOS does reserve a special
    handle for your printer (see: "Dos File Functions" above.)
       In order to keep the number of parameters down, the fhandle parameter
    is used to pass back the file handle and FOPEN is designed as a FUNCTION
    in assembler to return any error codes the same as a FUNCTION operates
    in BASIC.
       An error can occur if the file handle is invalid, the file is already
    open, file not found etc.  In this case, the errorcode or result will
    indicate what happened and any fhandle number should be ignored.

    Syntax:
    DECLARE FUNCTION fopen%(fil$, mode%, fhandle%)
    .
    .
    fil$="myprog.dat" : mode=0
    IF fopen(fil$, mode, fhandle) THEN
        GOSUB file.error
    ELSE
        PRINT fil$;" opened with a handle of ";fhandle
    END IF



    Name: FUNIQ                Type: Disk             Level: DOS
    FUNCTION

       This DOS disk file function creates a file with a unique name, which
    makes it ideal for scatch data files.  Rather than HOPING that
    "mydat.@@@" is a unique filename, FUNIQ makes SURE that a file is infact
    unique.  DOS will create such a file in the specified directory and open
    it with read write access with the attributes you specify.
       Furthermore, FUNIQ can, at your option, return the actual file NAME
    as well as the handle.  Enter the call with a string containing the
    desired drive and path where you want the unique file created, BE SURE
    to include a trailing backslash ("\")!   FUNIQ will return a file handle
    or error code and if you add 12 trailing spaces to the pathname, it will
    return the filename.
        More often than not, the unique name will be just 8 chars long, but
    if not it would only return part of the name.  When the unique name IS
    less than 12 characters the name will be padded with spaces which allows
    you to use BASIC's native RTRIM$ to fix it.

       NOTE: The unique file is OPEN with a handle!  Subsequent file access
    should be thru FWRITE et all or FCLOSE the handle and then access the
    filename via BASIC functions.
       NOTE: Use of FUNIQ requires DOS 3.0 or greater.

       See 'DOS File FUNCTIONS' for possible error returns


    Syntax:
    DECLARE FUNCTION funiq%(fil$, attrib, fhandle%)
    ..
    ..
    tempfil$="C:\BIN\            "
    IF funiq(fil$, 0, fhandle) THEN              ' path, normal file
       GOSUB invalid.path
    ELSE
       j=fclose(fhandle)                         ' close the handle
       tnum=FREEFILE                             ' get BASIC handle
       OPEN tempfil$ FOR APPEND AS #tnum         ' reopen file in BASIC mode
    END IF



    Name: FWRITE               Type: Disk             Level: DOS
    FUNCTION

      FWRITE sends simple strings to the file or device using a handle
    gotten from FOPEN.  DOS and FWRITE will handle larger data writes such
    as an array, but I am holding off implementing new array routines until
    we see what MicroSoft does with their array handling.
      An error may be generated for the same reasons as FOPEN, the error
    code is returned as a FUNCTION so as not to destroy the fhandle
    variable.
    Note: Be sure to include carriage returns and line feeds as needed, DOS
    takes nothing for granted!
    See 'DOS File Function for possible Error Returns'

    Syntax:
    DECLARE FUNCTION fwrite%(text$, fhandle%)
    ..
    ..
    tempfil$="C:\BIN\            "
    IF funiq(fil$, 0, fhandle) THEN              ' path, normal file
       GOSUB invalid.path
    ELSE
       text$="This is my data file - do not touch!"+CHR$(13)
       j=fwrite(text$,fhandle)                   ' write to the file
       IF j=6 THEN
           GOSUB invalid.handle                  ' error ?
       ELSE
           ignore = fclose(fhandle)              ' close file - we are done
    END IF



    Name: GETCH                Type: Keyboard         Level: BIOS

       Return keystroke from allowable string of selections.  Pass this
    routine a string of okay characters (in upper case) it will return
    which of those were pressed.  GETCH ignores input other than those
    characters in the okay$.  If passed a null GETCH string or a null
    return string, GETCG will return the first key pressed.  Additionally,
    2 features found in GETCH not in other routines of this nature, is that
    it will not get confused by any ANSI keyboard redefintitions and when
    used on a network, will not hang the terminal or server when called.
    See also PGETCH.

    Syntax:
    PRINT "Are You Sure?": ky$=" "
    CALL getch("YN", ky$)             ' allows input of Y or N only



    Name: GETFATTR             Type: Disk             Level: DOS
    FUNCTION

      Access to get the file attributes for a given file.  Subsequent calls
    to SETFATTR (see also) allow you to set or reset a file attribute.
    File attributes are as follows:
        00  -  Normal             04  -  System
        01  -  Read Only          32  -  Archive
        02  -  Hidden



      The archive bit is usually used by back up programs to determine if
    a file has been backed up since the last write process.  To combine
    attributes, just add the values, ie: Read Only - Hidden would be 3
    because 1+2=3.
       This is a function and therefore also returns any error code in the
    name of the function that can be evaluated itself, or assigned.  An
    error will result if the filename passed is not found (6).
    Error Codes:
    -1 = Invlid File attribute
     2 = File not found
     3 = Path not found
     5 = Access denied

    Syntax:
    DECLARE FUNCTION getfattr%(fil$, attrib%)      ' do before CLEAR or DEF
    .
    .
    fil$="myfil.txt"
    failure = setfattr(fil$, attrib)
    IF failure THEN PRINT "Sorry, cannot filnd ";fil$



    NAME: GETDSEG              Type: Misc              Level: Assembler

       This is more a development utility than a usable subroutine.  This
    returns BASIC's default Data Segment (DS).  In tinkering with calling C
    and routines from other languages, I've found this useful in making
    sure that the data segment is intact, also this may be required in
    determining parameters for routines in future releases.

    Syntax:
    dataseg=0
    CALL getdseg(dataseg)



    NAME: GETSTACK             Type: Misc              Level: Assembler

       Returns the state of BASIC's stack.  This is very helpful in
    determining what (if any) the stack should be set to, via a
    'CLEAR,,xxxx' statement at the start of your program.  The stack grows
    DOWNWARD with each successive GOSUB, so at strategic points in your
    code, calling GETSTACK and comparing it to the state of the STACK at
    the start of the program, aids in determining if you do need to include
    a stack statement at the start.

    stack=0
    GETSTACK(stack)


    NAME: GETVERFY             Type: DOS/System        Level: Assembler

       Returns the current VERIFY setting of the system.  This is NOT a
    read-after-write test as some think, but is where DOS does a CRC check
    of data just written to make sure it is write.  To CHANGE the VERIFY
    switch, use SETVERFY.  This routine returns 0 for OFF, nonzero for ON.





    NAME: GETDRV               Type: DOS               Level: Assembler

       This gets the default disk drive.  It returns an uppercase letter to
    avoid the confusion of drive numbering.  Again, since assembler
    routines cannot alter string lengths, be SURE to initialize the string
    variable to (at least) one space.

    Syntax:
    drv$=" "
    CALL getdrv(drv$)



    Name: GRAPH                Type: VIDEO             Level: QB

    This is an interesting sub-program.  It is one that you might not
    use very often, but should you ever need to figure out the algorithm to
    print either a vertical or horizontal graph based on a set of elements
    that you may or may not know the exact values of.

    Parameters:
    elements%() - holds the integer values to be graphed.
    basis%      - the total value basis.  In most cases this might be
                  the total of all the array elements, but in some cases,
                  you might only be graphing a portion of the total, ie an
                  "Other" or "Misc" category might not be included in the
                  elements% array, but for graphic accuracy, their total
                  would need to be part of the dividend used in GRAPH to
                  determine bar lengths.
    label$()    - A set of string labels corresponding to the elements%
                  array, to be placed below each bar.
    title$      - Title to be centered across the top of the graph.


    Unfortunately, at the present time due to screen limitations, the two
    graph routines handle a maximum of 10 elements to graph.  If passed
    more than 10, GRAPH will only plot the first ten items.  On the other
    hand, if passed less than 10 items to plot, GRAPH will adjust the
    spacing between each bar for aesthetics.  GRAPH will not plot 1 item.

    Syntax:
    ' stuff elmts%() with the values to be graphed
    ' stuff label$() with corresponding labels to use
    bas=145       'or whatever the total graphed and non-graphed items are
    title$ = "Productivity Graph"


   ' produce vertical graph:
    CALL vgraph(elmts%(), bas%, label$(), title$)

   ' produce horizontal graph:
    CALL hgraph(elmts%(), bas%, label$(), title$)





    Name: INCR / DECR          Type: Misc             Level: ASM

       There are people out there who made the tragic mistake of getting
    into one of those inferior BASIC dialects, and are having trouble
    adapting to QB.  INCR and DECR are meant to help alleviate this.
    If DECLARED as a SUB, they will work just like Turbo BASIC's native
    functions of the same name.

    Syntax:
    DECLARE SUB Incr%(x, y)
    DECLARE SUB Decr%(x, y)
    ..
    ..
    Incr i, 5                      ' same as i=i+5
    Decr j, q                      ' same as j=j+q



    Name: INSON / INSOFF       Type: Keyboard         Level: ASM

      This subroutine, simple puts the keyboard into INSERT ON state (INSON)
    or turns the insert toggle off (INSOFF).

    Syntax:  CALL inson
             CALL insoff



    Name: LASTDRV              Type: Disk / Sysytem   Level: DOS
    FUNCTION

       Returns the last logical drive installed in the system.  This returns
    the drive in DOS designator format, but the example shows the somple
    conversion to a letter.   This function will not alter the logged drive.

    Syntax:
    DECLARE FUNCTION lastdrv%
    ..
    ..
    drv=lastdrv
    drv$=CHR$(drv+65)+":"



    Name: LCOUNT              Type: Disk/String        Level: ASM
    FUNCTION

       This is a nifty routine to scan a disk text file for ASCII 13
    (carriage return) and will count them.  This is handy for sequential
    file I/O where you might want to inform the user how long processing
    will take or to replace a WHILE NOT EOF(x)....WEND loop with a
    FOR x=1 to LineCount....NEXT x loop.
       LCOUNT is a function that requires a valid file handle via FOPEN
    and an attempt to LCOUNT a standard DOS handle (1-4) will result in
    a LCOUNT of -1.  LCOUNT uses an internal 5 k buffer so it is incredible
    fast: GLIBDEMO at 50K takes only .5 seconds to count on an AT.




    Syntax:
    DECLARE FUNCTION lcount%(fhandle%)
    ..
    ..
    fil$="GLIBDEMO.BAS"                    ' text, not QB quick save format!
    result = fopen(fil$, 0, fhandle)
    IF result = 0 THEN
        LineCount=lcount(fhandle)
        IF LineCount > 0 THEN
           GOSUB calc.time
           PRINT fil$;" will require ";CalcResult;" minutes to process."
        ELSE
           GOSUB error.control
        END IF
    ELSE
        GOSUB error.control
    END IF




    Name: LNAMEF               Type: String           Level: ASM
    FUNCTION

      This data entry routine is handy for rearranging names from some
    other source to convert them to "Lastname, FirstName".  It works on
    names of all types, those with middle initials, just first and middle
    initials, multiple middle names.  It does not work correctly on Jrs,
    people who are the II, III or IV (ad nauseum).  In this case, I'd
    suggest using BASIC's INSTR and LEFT$ to trim off the Jr or II etc and
    append it after the LNAMEF call.

      All that is required is that the name have one single trailing space
    and another space where the names get swapped.  The function will fail
    and return a -1 if either condition is found to be not true. Samples:

    "Mary Beth J. Sandra Brooks " =>  "Brooks, Mary Beth J. Sandra"
    "P. T. Barnum Bailey "        =>  "Bailey, P. T. Barnum"
    "Thomas Q. Hanlon III "       =>  "III, Thomas Q. Hanlon"
    "John Public"                 => "John Public"  This one fails due to no
                                                    trailing space$

    Syntax:
    DECLARE FUNCTION lnamef%(text$)
    ..
    ..
    text$="Roy Burrows"+" "               ' MUST have trailing space
    result=lnamef(text$)
    IF INSTR(text$, "IVJrR") THEN GOSUB reformat.name

    IF result=0 THEN
       PRINT text$                        ' "Burrows, Roy"
    ELSE
       GOSUB reformat.name
    END IF




    Name: KBLOOP               Type: Keyboard, I/O     Level: QB

    This comes in quite handy in a number of situations.  For example:
    - As part of a waiting for keyboard input, you want to refresh part of
      the screen such as a time display.
    - More importantly, if you have a security routine where you have the
      user enter a logon or ID code, then a function they want to perform,
      you might want to back up to the security code entry point if after
      a valid code is entered a number of seconds passes before a
      function is selected.  In such a situation, someone else on hand
      would have access to the system or functions under the guise of the
      identity of the person who entered the security code.
      Thru the use of KBLOOP, if a function is not selected within a
      certain number of seconds after the ID is, you can loop the program
      back to some other starting point.


    Parameters:
    kbin$ -  On the call set this to SPACE$(x) where x is the number of
             characters to wait for ie if kbin$=SPACE$(3), then KBLOOP will
             loop until the return string is 3 characters long.
             Returned in kbin$, is the actual characters entered.


    looptime - This is the length of time you want KBLOOP to loop
               internally waiting for x characters to be entered.
               If the time expired, this returns as Zero.


    Syntax / Example:

    label1:                 ' demo for a security routine
    kbin$=SPACE$(3) : LoopTime=30
    CALL kbloop(kbin$, LoopTime)

    IF LoopTime=0$ THEN GOTO label1
    ' This could also be a DO WHILE...LOOP routine.



    Name: MCSRINC / MCSRDEC    Type: Mouse            Level: BIOS

       Mouses are curious things.  Each call to turn off the mouse cursor
    requires an equal number of cursor-on calls to redisplay the cursor.
    The mouse driver tracks what is called an internal cursor flag.  Each
    call to turn off the cursor decrements the counter, each cursor-on
    call increments it and if (and only if) the internal flag is 0, the
    cursor is displayed.  Therefore each call to decrement the flag, needs
    one increment call if the cursor is to be displayed.  And this does
    NOT work the other way, if the cursor is on (flag=0) an additional
    call to increment the flag has no effect.  Finally, we have no access
    to be able to read what the cursor flag is to know how many MCSRINC
    calls we need to make to display the cursor.



       If you are new to mouse programming, beware: if you update the
    screen with the mouse cursor on, it will leave little reverse video
    blocks all over, and at times, doing a MSETXY with the cursor on will
    produce 2 cursors: one at the old and another at the new location.  To
    avoid this, turn the mouse cursor off before screen updates, including
    (indeed, especially with) screen saves and restores and forced mouse
    cursor relocations.
       MCSRINC and MCSRDEC do just that - increment or decrement the
    cursor.  Knowing what you do now, it would make sense to track a copy
    copy of the internal flag in your program.  If in the course of your
    program you want to BE SURE that the sursor is on or off, performing a
    call to MCSRON or MCSROFF will do so.  However in so doing, the mouse
    is reset: x and y range limits, cursor masks, mickey factors, the
    works.      SEE ALSO MCSRON, MCSROFF

    Syntax:                  Logical Equivalence
    CALL mcsrinc             ' InternalFlag=InternalFlag + 1
                             ' IF InternalFlag=0 THEN ShowCursor

    CALL mcsrdec             ' InternalFlag=InternalFlag - 1
                             ' IF InternalFlag<>0 THEN HideCursor




    Name: MCSRON / MCSROFF     Type: Mouse            Level: BIOS

       Reset the mouse to power on state and force an unconditional cursor
    on or off.   See also MCSRINC/MCSRDEC.

    Syntax:     CALL mcsron
                CALL mcsroff


    Name: MGETXY               Type: Mouse            Level: BIOS

       As you could expect, this gets the current X,Y location of the
    mouse.  Note that the location of the 'normal' cursor has no bearing
    on what this returns.  Nor does it matter if the mouse cursor is on or
    off: MGETXY returns the CURRENT location of the cursor, NOT the LAST
    SEEN location.  Unlike some inferior "other" QB libraries, MGETXY and
    MGETXY (see also) use and act upon 80x25 coordinates, not pixel mode
    that you have to convert.

    Syntax:
    REM get mouse cursor
    CALL mgetxy(MouseRow, MouseCol)

    REM set Mcursor position to normal cursor position on double right click:
    CALL mrelease(Lbutton, Rbutton)        ' get current status
    IF rbutton>= 2 THEN                       ' what is the right status?
       CALL mgetxy(Mrow, Mcol)                ' get mouse location
       LOCATE Mrow, Mcol                      ' set location
    ELSEIF lbutton=>2 THEN                 ' double left
       SYSTEM
    END IF
    Lbutton=0: Rbutton=0                   ' Clear count



    Name: MLONG / MNORM        Type: Mouse            Level: BIOS

       You can also control the sensitivity of the mouse.  The ratio by
    which one mouse inch moves x number of characters or pixels on the
    screen is called the Mickey Factor.
       Unaltered, the default Mickey Factor of the New Microsoft Mouse is
    about 2 inches to move the cursor all the way across the screen and 1
    inch to travel the vertical distance of the screen.  MLONG alters the
    Mickey Factor so that it takes about twice as much desk space to
    travel the same screen distance: 4 inches horizontally, 2 inces
    vertically.
       MNORM resets the Mickey back to 2 horizontally, 1 vertically, as
    does a call to MCSRON (see also MCSRINC, MCSRDEC).




    Name: MRELEASE / MPRESS    Type: Mouse            Level: BIOS

       These mouse routines return the number of mouse button RELEASES and
    PRESSES since the last time the mouse driver was polled.  One obvious
    use of these two routines is to poll the driver to see if a double
    click has been executed since the last poll (say, while the program
    was off doing a disk access or such).

    Syntax:
    CALL mrelease(lbutton, rbutton)
    CALL mpress(lbutton, rbutton)



    Name: MSETXRNG / MSETYRNG  Type: Mouse            Level: BIOS

       MSETXRNG and MSETYRNG allow you to limit the minimum and maximum
    X and Y range that the mouse cursor is to be allowed to roam in.  A
    use for this would be to limit the mouse to an area in a window or a
    menu.  Further, this routine is suitable for use in either text or
    graphics modes thru a flag.

    Syntax:
    REM limit mouse area to a box of 5,1 to 12,40 in 80x25 mode:
    TextMode=1
    MinR=5: MaxR=12
    CALL msetxrng(TextMode, MinR, MaxR)
    MinC=1: MaxC=40
    CALL msetyrng(TextMode, MinC, MaxC)


    REM limit mouse area to horiz positions 100 - 150 (640x200):
    TextMode=0
    MinR=100: MaxR=150
    CALL msetxrng(TextMode, MinR, MaxR)



    Name: MSETXY               Type: Mouse            Level: BIOS

      This is the simple inverse of MGETXY, setting the current mouse
    cursor position.  MSETXY works off of 80 x 25 based coordinates so
    that you need not think in 80x25 for text and character output and
    mentally switch to pixel based locations for mouse I/O.
      Note that the mouse cursor normally seems to default to center
    screen (12,40) with a simple cursor on call (MCSRINC, MCSRON).

    Syntax:
    REM set Mcursor position to row 20, column 60
    MouseRow=20: MouseCol=60
    CALL msetxy(MouseRow, MouseCol)



    Name: MTYPE                Type: Mouse            Level: BIOS

       This routine returns whether a mouse exists or not as the number of
    mouse buttons.  Naturally, that means 0, 2 and 3 are the only MTYPE
    returns you should expect.

    Syntax:
    CALL mtype(MouseExist)
    IF MouseExist THEN
       ..
       ..
    END IF


    Name: MSETCSR              Type: Mouse            Level: BIOS

       This is a rather specialized routine for the mouse.  Some of the
    less compatible mice require a littel tweaking to get the cursor to
    display.  If you have trouble getting a cursor to display, calling
    MSETCSR should set the mask so that it does display when the cursor
    is on.  It appears to have no ill effect on mice who do not need it.

    Syntax:  CALL msetcsr


    Name: MHZ                  Type: Hardware          Level: BIOS

       This returns the approximate, effective Megahertz the system is run
    at.  Sound vague enough?  This return is the result of a very quick
    benchmark that it runs.  It is "approximate, effective" Mhz because
    it will be off a little depending on the number of wait states of the
    machine, and some faster PC clones return falsely high numbers.  This
    used to be part of CPUINFO, but because the CPU chip type and NDP chip
    are more useful and frequently called upon information and because the
    MHZ test does take a little while to run, I have split them up.
       MHZ returns the speed factor as a whole number: that is a return of
    935 means a effective MHZ speed of 9.35.  Divide the return by 100.
    It is advised that you cross reference the speed with the chip:
    if MHZ returns 1400 but CPUINFO indicates a 8088 machine, you know the
    speed is wrong and that the PC is more likley 8 to 10 MHz.
       This also acts just a touch flaky on some machines that I would call
    it once if I had to and store the number so as to have an idea of the
    system the program is on (esp w/ SINFO), but do not call it repeatedly.


    Name: MDLY                 Type: Misc              Level: BIOS

    MDLY works like DLY in that it enables you to insert controllable
    delays or slow downs into your code for effect or to allow the end user
    time to digest the screen.  MDLY halts processing a given number of
    milliseconds and works out great when a full second is too long.  MDLY
    appears to be accurate to about .055%.

    Syntax:
    CALL mdly(500)        ' delay .5 seconds
    CALL mdly(100)        ' delay .1 seconds



    Name: MENUCTRL             Type: Keyboard          Level: BIOS

    MENUCTRL is a keyboard - menu control module that is totally Network
    Compatible to trap specific keys, as such is ideal for menu driven
    routines.  When called, the routine intercepts all keyboard activity
    exiting only if a number key or function key is pressed - any other
    input is ignored.  MENUCTRL returns the value of the key or function
    key pressed, ie '1' and/or '[F1]' return 1, '2' and/or '[F2]' returns 2
    etc.  Pressing [Esc] returns 15.    These return codes are compatible
    with FED.



    Name: NFRMAT               Type: String            Level: QB

    This routine allows for extensive numeric string processing.  You can
    have it check an entry to make sure it is only numeric, allow or
    disallow "-" as a delimiter, and also have it format it to a 7 or 10
    digit phone number or even to social security format or an account
    number type format.

    Parameters:
    st$ =  string to process (presumably numeric)
    p = position of a single "-" for mode 6 (account number processing)
    m = mode or level of processing to perform (see below)

    mode 0 = Disallow "-" as an element.  This mode will check for
             purely numeric input, rejecting anything and everything else.
             (See Error Returns Below).

         1 = Allow "-" as an element.
             If your application is to allow some user formatting, this mode
             will allow the delimiter "-" as an element of the sting.  Note
             that there can be any number of "-"s and that they can appear
             anywhere! Use with care!

         2 = Formatting to phone type (7 digit: xxx-xxxx)
             This will format a numeric string as shown above,
             returning an error if any element of the string is non-numeric
             and not a "-".

         3 = Formatting to phone type [10 digit: (xxx) xxx-xxxx]
             This will format a numeric string as shown above,
             returning an error if any element of the string is non-numeric
             and not a "-".


    Note: As of yet, there is no universal phone number formatting, ie you
    must anticipate the correct 7 or 10 digit format.  Sending to mode 3 a
    7 digit string will result in an error as will sending to mode 2 a 10
    digit string.  I hope to be able to circumvent this in future versions
    of the LIB.  Also mode 3 (10 digit phone) will return an error if area
    code delimiters "(" and ")" are included.


          4 = Formatting to social security style [xxx-xx-xxxx]
              This will check to see that no non-numeric characters are
              are being sent, and that they are not "-" (ie "-"s are
              allowed"), then it will format it as shown above.  Letters and
              other non numeric charcters (except "-") will return an error
              code, as will a length other than 9.

          5 = Extract numbers from string sent, no exclusions.
              This one has little value in that severe errors can result:
              all we are doing is extracting the numeric characters from the
              input string and sending them back.  The only way that this one
              should be used would be to "screen" input by send a string to
              NFRMAT via mode 5 then sending the return BACK to NFRMAT via
              mode 2,3 or 4.

           6 = Extract numbers, place "-" in position p.
               This mode will allow for an account number style formatting
               by allowing you to define in what position a "-" should be
               placed.  Sorry, but "-" is the only delimiter currently
               allowed, and is only one of them returned per string.  This is
               to keep the number of parameters passed to a minimum.  To
               effectively get 2 "-"s into an 'account number' make 2 passes
               to NFRMAT via mode 6:

     To get 316-6848-744 out of 3166848744:

     INPUT "Account Number", st$               'receive 3166848744
     m=5:p=0
     CALL nfrmat(st$,m%,p%)                 'strip off -'s incase

     st1$=LEFT$(st$,5)                      'st1$ is now "31668"
     st2$=RIGHT$(st$,5)                     'st2$ is now "48744"
     m=6:p=4                                'mode 6 with "-" as 4th char

     CALL nfrmat(st1$,m%,p%)                'makes st1$ into "316-68"
     p=3                                    'set up for next pass
     CALL nfrmat(st2$,m%,p%)                'makes st2$ into "48-744"

     st$=st1$+st2$                     '"316-68" + "46-744" = "316-6846-744"

          While this is a round about way of getting 2 "-"s into it, it does
      do the trick.  If there is sufficient call for multiple delimiters
      and/or different delimiters, I can make "mode 6" a separate function
      from NFRMAT to allow programmer defined delimiters and support multiple
      delimiters...let me know.



    Syntax:

    DEFINT A-Z
    INPUT "Enter social security number",st$   'they key in 123456789
    m=4 : p=0

    CALL nfrmat(st$, m, p)
    PRINT st$                            'program returns 123-45-6789


    Mode 5 Example:

    DEFINT A-Z
    INPUT "Account Number:",st$          'they key in 3kj';lk9123
    m=5 : p=114                            'p can be anything - see below
    CALL nfrmat(st$,m%,p%)
    PRINT st$                            'output would be 39123


    Mode 6 Example:

    DEFINT A-Z
    INPUT "Account Number:",st$               'they key in 3145678
    m=6 : p=3                                 'place a - in position 3
    CALL nfrmat(st$,m%,p%)
    PRINT st$                                ' output would be 31-45678


    Note: REGARDLESS of what mode is used, the positional parameter 'p' must
    be defined and passed!


                               ERROR RETURNS
                               -------------
    If the string sent does not conform to the specifications you define by
    the mode assignment, NFRMAT will return an error code and an error
    message.  The string message will be returned in st$ and a code in m.
    (See ERRMSG.)

   M Return    ST$ Return
   --------   ----------
     99       "Numeric Entry Only!"
     98       "Too long-Looking for xx Digit [Phone/Social Security] Number!"
     97       "Too short-Looking for xx Digit [Phone/Social Security] Number!"
     50       "Programmer Error - Invalid mode specified."
                         (you screwed up!  This is also returned if p is not
                          defined or passed.)

     If all went as expected:
     M    =   Numeric string formatted to specifications.



    Name: NLON / NLOFF         Type: Keyboard          Level: BIOS

    Sets the Keyboard Num Lock key to on (NLON) or off (NL OFF).



    Name: PCASE                Type: String            Level: Assembler

    Converts a passed test string to 'proper case'.  That is, "bob smith"
    is returned as "Bob Smith".  Prior to calling PCASE convert the string
    to lower case.

    Syntax:
    CALL pcase(n$)



    Name: PGETCH               Type: Keyboard / Video    Level: BIOS

       This routine is similar to GETCH in that it allows keyboard input
    only from a predefined string, is ANSI compatible and Network
    functional, but additionally allows the addition of an automatically
    centered prompt.  By predefining a number of prompts and input masks, a
    variety of easy to use prompt-and-allowable-input-masks can be setup
    for very easy use.  See also GETCH.

    Syntax:
    REM display prompt on line 24, in yellow on red, allow only Y, N or A
    prompt$="Are You Sure Y/N/Abort": okay$="YNA" : row=24: ky$=" "
    CALL pgetch(prompt$, row, 78, okay$, ky$)



    NAME: PFILE                Type: Printer           Level: DOS

      Send a file from disk to the first printer (LPT1, PRN etc).  This is
    a much handier way to print a file rather than reading it line by line
    and LPRINTing it, and takes mush less memory than SHELL to DOS and
    copying it to the printer.   To cut down on disk I/O and speed up the
    overall operation, this routine reads in 4k blocks of the file, this
    does not act as a spooler however, since the routine will not return
    until the buffer is empty.  This routine does not abort if the printer
    is not ready, test for printer readiness with PSTAT.  As with all GLIB
    routines, you need not make the filename ASCIIZ, that is a job best
    left to assembler!

    Syntax:
    printfil$="GLIB14.DOC"
    CALL pfile(printfil$)



    Name: PINIT                Type: Printer           Level: BIOS

    Here is a handy routine: it initializes the printer, and if the offline
    button has sent it offline, it will put it online (Epsons anyway) and
    set the printer to TOF (Top Of Form).  Call it with the designated
    priter port to initialize (1 to 3 - Lord knows what it will do if you
    try to initialize printer # 53.7).  See also PSTAT.

    Syntax:
    printernum=1
    CALL pinit(printernum%)




    Name: PRTSCRN              Type: Printer           Level: BIOS

    This very simply sends the current display to the printer.  No
    arguments are passed, used or returned.

    Syntax:
    CALL prtscrn



    Name: PSTAT                Type: Printer           Level: BIOS

      Where PINIT intializes the printer, PSTAT returns the status of a
    designated printer in the form of  0, -1 so you can use the parameter
    passed in IF THEN statements.  Pass PSTAT the printer number to test
    (1-3) as a variable and the variable will be returned as 0 or -1
    indicating the staus.
    NOTE:  When testing the status immediately after calling PINIT, allow 1
    or seconds before calling PSTAT, this is to avoid polling the printer
    while it is still initializing.

    Syntax:
    -------
    prtnum=1
    CALL pinit(prtnum%)
    CALL dly(2)                   ' wait for the low tech item to get done
    CALL pstat(prtnum%)
    IF  prtnum THEN
       ...perform print job ...
    END IF



    Name: QUIKPRT              Type: VIDEO             Level: BIOS

    This is a replacement for BASIC's painfully slow PRINT function.  It is
    another implementation of the original quick print routine that was in
    BYTE magazine a few years ago.  As the demo shows it is faster than
    PRINT on an order of magnitude.  QUIKPRT correctly distinguishes EGA's
    and MONO systems from CGA's and proceeds to QUIKPRT in fast mode.  On
    CGA systems, it monitors the retrace to avoid snow.

    Parameters:
    text$ - Text string to QUIKPRT to the screen
    row - Row of screen to print text to.
    col - Column of screen to print to
    attr - color attributes to use for the text.  This is calculated in the
           same manner as the attribute is for WDW, ERRMSG and others that
           use it:
           attr=(BACKGROUND * 16) + FOREGROUND

    Syntax:
    msg$="QUIKPRT is very, very FAST !!"
    attr=(4*16)+14
    CALL quikprt(msg$, 2, 2, attr%)
    or directly,
    CALL quikprt("QUIKPRT is very, very FAST !!", 2, 2, 78)



    Both examples produce the same results: the message is printed on row
    2, column 2, in yellow-on-red.

    Eg:
    qprt:     'fills the screen quickly with the contents of the msg$ array.
       FOR x= 1 to 25
          CALL quikprt(msg$(x), x, 1, attr%)
       NEXT x
    RETURN



    Name: RAMFREE              Type: Equipment         Level: BIOS

    Returns the amount of memory installed in the machine.

    Syntax:
    mem=0  :  CALL ramfree(mem%)
    PRINT "Free memory amount is: ";mem


    Name: READSCRN             Type: Video             Level: BIOS

       This is like BASIC's SCREEN function except that it is much faster
    (on an order of magnitude) way to read text from the screen.  READSCRN
    uses the current cursor location as the starting point and reads as many
    characters as you have spaces in the passed string.  This is critical,
    since ASM routines cannot alter string lengths, if you want 13
    characters, text$ must be initialized to SPACE$(13).

    Syntax:
       scrntext$=SPACE$(13)
       locate 12,15
       CALL readscrn(scrntext$)



    Name: RINSTR               Type: String            Level: DOS
    FUNCTION

       Returns the LAST occurance of a character in a string.  This works
    conversely to DOS's INSTR, which returns the first occurance, and is
    faster and much more code efficient than a loop to keep testing INSTR
    until the end of the string is reached.  The character location however
    is still returned from the left.
       Note: RINSTR works only on character seeks, not on sub strings
    like BASIC's INSTR does.  That is, in the case of
    j=rinstr("ABCDEFG","A@B")
    RINSTR will only seek and match on "A", not "A@B".  Multiple passes thru
    RINSTR, however seeking each successive character in a sub string could
    be accomplished.

    Syntax:
        DECLARE FUNCTION rinstr(searched$, seek$)
        ..
        ..
        test$="123456x890" : char$="x"
        l = rinstr(test$, char$)                   ' returns 7




    Name: SVSCRN / RSTSCRN     Type: Video             Level: BIOS

      The SVSCRN routine saves the current screen display to an integer
    array then via RSTSCRN you can restore that saved screen to the
    display.  This is very handy in a routine in situations where you might
    want to pop a help window to the display.  You could save the current
    screen, display a help window or screen, then upon command redisplay
    the original screen.
       The array which we save to and from MUST be DYNAMIC, ie it must be
    allocated off of the far heap.  This is done via any of the three
    following ways:
    1) REM $DYNAMIC
       DIM scrnarry(2000)

    2) REDIM scrnarry(2000)

    3) j=2000 : DIM scrnarry(j)

    Parameters:
    In telling SVSCRN or RSTSCRN where to put or get screen contents, we
    do not pass the entire array, but a a pair of pointers pointing to
    the segment and the offset of the array.

    In QB4 this is done with the keywords VARPTR and VARSEG:
    segment=VARSEG(scrnarry(1)) )  : offset=VARPTR(scrnarry(1)) )

    We now have determined the segment and offset of the array and can
    continue with the call.

    Next, understand that each screen will require 2000 bytes to store;
    the array to hold the screens would need to be in multiples of 2000 for
    each screen.  To save 3 screens, dimension the array to 6000, if you
    plan to be swapping 2 screens, dimension it to 4000.

       Once you have the space set aside for the screen elements, before we
    can store a screen there, we need to set a pointer to the array.  That
    is, if we DIM sarry% to 6000, there is room for 3 screens, but before
    we can store a screen there, we need to tell the routine WHERE in the
    array to store the screen.  The idea is to point a variable at 2000
    byte intervals in the array for the different screens.

    Variable pointing to:                                Points to:
    ---------------------                               -----------
    Scrnarry(0)                                         Screen number 1
    Scrnarry(2000)                                      Screen number 2
    Scrnarry(4000)                                      Screen number 3

    (If using OPTION BASE 1, use scrnarry(1), scrnarry(2001) etc)

    One other thing to remember is that the being a DYNAMIC array, BASIC
    will move the array around in memory as it sees fit depending on what
    your code is doing.   Therefore, prior to EACH call to SVSCRN or
    RSTSCRN you must set or reset the segment and offset pointers.  I
    suggest that you do this via a GOSUB type subroutine:



    GOSUB SetPointers
    CALL svscrn(segment, offset)
    ...
    ...
    ...

    SetPointers:                   ' QB 4 version
      segment=VARSEG(scrnarry(1)) )
      offset =VARPTR(scrnarry(1)) )
    RETURN


    Syntax:
    -------
    CALL svscrn(segptr, offset)       ' save current screen to position one
    CALL rstscrn(segptr, offset)     ' restores screen from position 3

    Alternatively, for QB4:
    CALL svscrn(VARSEG(scrnarry(1)), VARPTR(scrnarry(1)) )

    For more information, examine the demo source code, as these 2 routines
    are used quite a bit.  In the demo, a deliberate delay is used in
    some cases to slow down the save and restore process to allow you time
    to perceive the process.



    Name: SETFATTR             Type: Disk             Level: DOS
    FUNCTION

      SETFATTR allows you to change or modify the file attributes for any
    disk file that exists.  For a table of the attributes, see GETFATTR.
    SETFATTR is also a function and will return any error code in the
    function name allowing you to use it in a statement or assign it.
       SETFATTR checks for, and allows only valid file attributes, volume
    labels and directories are not supported.


    Syntax:
    DECLARE FUNCTION setfattr%(fil$, attrib%)
    .
    .
    fil$="myprog.sys" : attrib=3             ' make it Read Only, Hiddden
    IF setfattr(fil$, attrib) THEN
       PRINT "Error - possible invalid file attribute."
    ELSE
       PRINT "Change succeeded."
    END IF





    Name: SYSTIME              Type: System            Level: BIOS

       Rather than tearing apart BASIC's TIME$ with MID$ to determine the
    current hour, minute, second, SysTime allows instant access to all that
    PLUS the hundredths of a second with no string garbage generated.  Note
    that not all Clone BIOSes support hundredths of a second in the BIOS,
    so it may not be accurate on all systems.

    Syntax:
    CALL systime(hrs, min, sec, hunds)



    Name: USCROLL / DSCROLL    Type: Video             Level: BIOS

    These 2 routines scroll a portion (or all) of the current display
    up or down a user defined number of times.  SCROLL allows for you to
    set the parameters for all four boundaries: top, bottom, left and right
    Additionally, you designate the number of lines to scroll.  Designating
    0 as the number of lines to scroll, clears the screen.


    Parameters:
    Top, left, bottom and right, relate to the bounds of the area to scroll,
    and they are listed in the same order as are used in WDW for uniformity.


    Syntax:
    num=12 : top%=1 : lft=1 : bttm=12 : rght=79
    CALL DSCROLL(num%, top%, lft%, bttm%, rght%)
        ' scrolls lines 1 to 12 down 12 lines - lines 13 to 25 are lost

    CALL uscroll(12, 13, 1, 25, 79)
        ' scrolls lines 12 to 25 up 12 lines -  with 13-25 becoming blank.

    CALL dscroll(25, 1, 1, 25, 79)
        ' Clears the screen with the display scrolling down off the screen



    NAME: SCROLLER             Type: Video             Level: BIOS

       This routine scrolls the entire screen left or right a designated
    number of lines.  For simplicity, the entire screen is scrolled or
    shifted eliminating the need for top, bottom etc co-ordinates.  A
    positive number scrolls the screen to the left, a positive number
    scrolls to the right.  Note that this is not a true scroll, but rather
    a creative implementation of the quick print algorithm.  Regardless, in
    the demo you will see that the result is so fast, especially on 286
    machines, that the insertion of a very short delay sometimes ADDS to
    the effect of the display.

    Syntax:

    CALL scroller(4)
    CALL scroller(-6)



    Name: SCRLON / SCRLOFF     Type: Keyboard          Level: BIOS

    Toggles the scroll lock key on or off.  If the keyboard is equipped
    with LED's, they are also toggled to the appropriate state.

    Syntax:

    CALL scrlon
    CALL scrloff




    Name: SCRNDUMP            Type: Video, Printer    Level: QB

    This does just what the name implies - it sends the screen display to
    a disk file.  In many cases, your program may adequately be able to
    send output to disk, but if you have a graphic display that you want to
    send to disk, or your application has a screen dump function, you might
    find this of help.

    You have control of the file mode: the screen dump can append to an
    existing file or you can let it be the only thing in the file. SCRNDUMP
    neither opens or closes any file.

    Parameters:
    You need to pass the file handle (number) to SCRNDUMP.

    Syntax:
    OPEN "scrndump.fil" FOR APPEND AS #6       ' tacks current display to
    CALL scrndump(6)                           ' file if it exists.
    CLOSE #6

    num=4
    OPEN "screen.fil" FOR OUTPUT AS #num       ' Kills existing file
    CALL scrndump(num%)                        ' then puts screen display
    CLOSE #num                                 ' to that file



    NAME: SETDRV               Type: DOS               Level: Assembler

    Sets or resets the default drive.  To set the drive, simply pass it the
    letter, upper or lower case, to log into.  This removes the ambiguity
    of drive numbers (Hmm, is drive 1 A: or B: in this case....).  SETDRV
    returns nothing and if passed a bad parameter, DOS simply rejects it
    leaving the default drive unchanged.

    Syntax:
    drv$="d"
    CALL setdrv(drv$)



    Name: SETERR               Type: DOS Terminate     Level: DOS

       Sets return code upon program termination.  These can be read from
    DOS via as "ERRORLEVELs" in batch files.  This routine MUST be CALLed
    at the VERY END of a program, as the DOS interrupt used to set return
    codes (the so-called ERRORLEVELs) WILL terminate your program.  It is
    also not possible to CALL this routine from inside the compiler
    environment as it will drop you to DOS after the call.  For this reason,
    it is not included in the environment libraries as prepared by me.


    Syntax:
    ------
    CALL seterr(code)                 ' terminate and set "ERRORLEVEL"

    Example:
    IF x=0 THEN PRINT "Normal ";: ELSE PRINT "End of job."

    IF x<>0 THEN PRINT "ERRORLEVEL set to ";x
    CALL seterr(x)



    NAME: SETVERFY             Type: DOS/System        Level: Assembler

    Sets or resets the DOS VERIFY switch (see GETVERFY for an explanation
    of VERIFY).  Note that if you intend to alter such a system switch, it
    is good programming practice to restore it to its original setting when
    your program terminates, this switch can be determined via GETVERFY.
    In calling SETVERFY, 0 turns VERIFY OFF, 1 turns it ON.

    CALL setverfy(0)
    CALL setverfy(1)



    Name: SINFO                Type: MISC              Level: BIOS

    Returns some simple, basic hardware or system info.

    Parameters
    RAM - Returns the amount of DOS memory installed
    SER - Returns number of serial ports installed
    PAR - Returns number of parallel ports installed
    EGA - Returns KB of installed EGA memory, 64, 128 or 256KB
          If no EGA is available, ega will return 0.
    VGA - Returns 0/1 if VGA is installed.

    Syntax:
    CALL sinfo(RAM, SER, PAR, EGA, VGA)



    Name: TFRMAT               Type: String            Level: QB

    TFRMAT allows for Time string formatting similar to that in DFRMAT.
    There is no error checking for the correct time being set, (how can there
    be?), but if the mode parameter is not set right, an error message of:
    " Invalid mode specified" will be returned in T$, also m will be set
    to 50.

    Parameters:
    label 0 = OFF   (none)
          1 = am/pm

    nutime$ = Returned, formatted time string.

    Syntax:                                  Output:
    PRINT TIME$                              13:01:01
    CALL tfrmat(nutime$,1)
    PRINT nutime$                             1:01 pm



    Name: VFNAME               Type: Disk/String       Level: DOS
    FUNCTION and SUB

        VFNAME checks a string you pass it to determine if the string indeed
    is capable of bing a valid filename.   Pre testing a string that you may
    have gotten from end user input, helps avoid runtime errors later on and
    in the case of novice end users allows considerable feedback from your
    program on what is wrong with a filename typed in.

        The process is twofold - it tests for characters such as ,[>< and
    also attempts to open the file and returns an error code.  In the case
    of the character test, the FUNCTION returns 0 if it finds no offending
    characters, or the ASCII value of any invalid filename character.  This
    allows you to be able to give apparently intuitive feedback to a users
    on valid filename characters.

        A second pass is needed to test drive and path validity.  The colon
    and backslash are not tested for as invalid chars since they ARE valid
    IF in the right spot.  To test this, VFNAME attempts to open or create
    the file thus returning info on the path, access and if the file already
    exists.  Any DOS feedback is returned as a formal parameter:
    3 - Drive or path not found
    4 - No handle available ("Too Many Files")
    5 - Access denied (already opened on multi system)
    80 - file exists.

        Note: VFNAME does NOT actually create or open the file!  It just
    pre-tests for any possible runtime error in trying to do so.

        Note: VFNAME requires DOS 3.x




    Syntax:
    DECLARE FUNCTION vfname%(fil$, DOScode%)
    ..
    ..
    getfname:
       LINE INPUT "File to Write Data to: ",fil$

       CharCode = vfname(fil$, DOSCode)
       IF CharCode THEN
          PRINT "Sorry, but '";CHR$(CharCode);"' is an illegal in filenames!"
       END IF

       SELECT CASE DOSCode
           CASE 0                   ' no DOS error or was not tested
                                    ' because fil$ had CharCode - do nothing

           CASE 3                   ' goofy path/drive
             PRINT fil$;" has an invalid drive or path in it.  Try again."

           CASE 4                   ' handles exceeds FILES= in config.sys
             GOSUB close.some.files
             DOSCode = 0            ' clear error for below

           CASE 5                   ' no access rights!
             PRINT "Pick a new name.  You do not have access to ";fil$

           CASE 80                  ' file already exists
             PRINT fil$;" exists. Overwrite it?"
             INPUT "",yorn$
             IF UCASE$(yorn$)="Y" THEN DOSCode=0     ' clear error

           CASE ELSE
             GOSUB something.really.weird.happened

       END SELECT

       IF DOSCode THEN GOTO getfname     ' loops if DOSCODE = 3, 5 or 80
                                         ' with no overwrite
    ..
    ..


    Name: VIDOFF/VIDON         Type: Video/hardware    Level: BIOS

        Similar to a screen saver program, this routine will turn off any
    monitor (we hope - tested on CGA, EGA and Composite so far).  If a
    timing loop in your long running program senses no activity for x
    minutes, a call to VIDOFF will trun off the display, then once you sense
    activity again, VIDON restores the display.
        This should accurately detect mono, CGA and EGA systems and
    correctly turn them on or off, I do not have any or info on VGA systems
    to tell if it will work on them (though I doubt it is necessary on
    them).

    Syntax:    CALL VIDOFF : PRINT "Hi, Pal" : BEEP : CALL VIDON





    Name: WDW                  Type: Video             Level: BIOS

       An extensive windowing routine, allows for frames, sound, color
    control and a growing effect.  The routine requires numerous arguments
    passed, but be warned that NO error checking takes place as to accurate
    or misplaced coordinates.  Really far out coordinates can lock up the
    machine (such as locating the bottom of the window ABOVE the top
    etc...) so be sure to save your work BEFORE test running a program with
    a window call.
       This routine offers a "growing" effect and a sound effect, both of
    which are optional thru the use of the parameters sent.  The grow
    effect is most effective on narrower windows as opposed to wider ones.
       Previous versions allowed your application to chirp or not chirp
    based on an environment switch ( SET GWDW=/Q ).  This implementation
    no longer recognizes this switch, however hope reigns supreme that it
    will again in the future.  On the other hand, being in assembler, the
    grow effect is MUCH more acceptable.


    Parameters

    top   - Top row of window to be displayed.
    lside - Left border of window to be displayed.
    bttm  - Bottom row of window to be displayed.
    rside - Right border of window.
    sfx   - Sound effects toggle, 0=OFF 1=ON
    grow  - Grow switch, 0=OFF 1=ON
    frame - Style of frame to use for the window:
            1 - Double Lines Horizontal  / Double Lines Vertical
            2 - Double Lines Horizontal  / Single Lines Vertical
            3 - Single Lines Horizontal  / Single Lines Vertical
            4 - Single Lines Horizontal  / Double Lines Vertical
    attr  - Attribute of window to be displayed
            Calculated by (BACK_COLOR * 16)+FORE_COLOR
    label - String to display centered across the top of the window.
            If no label is desired initialize to "".

    Syntax
    ------
    top%=2 : lside%=2 : bttm%=5 : rside%=79 : sfx%=1 : gro%=1 : frame%=1
    attr%=78 : label$=" A long window across the top of the screen "

    CALL wdw(top%, lside%, bttm%, rside%, sfx%, gro%, frame%, attr%, l$)

    Puts a window to the screen from 2,2 to 5,79, with a chirp sound
    effect, with a double / double line frame with a yellow foreground on a
    red background.