DP Tool Club 24/CD_ASCQ_24_0995.iso/vrac/homonlib.zip/README.TXT

Text File | 1995-04-13 | 9KB | 196 lines

*****************************************************************************
                                HOMONLIB 1.0
                                     by
                              Raymond W. Marron
                           HOMONCULOUS PROGRAMMING
                                  Mesa, AZ
*****************************************************************************

INTRODUCTION:

     HOMONLIB is a collection of functions and subs for use with QuickBASIC.
It was written and tested using QB 4.5 on an IBM/MS-DOS compatible machine.
Earlier versions of QB may work, but have not been tested.  Using HOMONLIB
with the QBASIC supplied with versions of DOS 5.0 and higher will be
difficult at best, mainly due to it's lack of things such as the $INCLUDE
directive.

     HOMONLIB is distributed as freeware and may be passed around or uploaded
to online services with the blessing of the author.  All I ask is that only
the original, unmodified HOMONLIB.ZIP be distributed in its entirety.  If
necessary, the name may be shortened to HOMON.ZIP if an online service has
filename length restrictions.

     All files included in HOMONLIB.ZIP are copyright 1995 Raymond W. Marron/
HOMONCULOUS PROGRAMMING.  You may use all or part of HOMONLIB in your
personal or commercial programs with no royalty or fee due to the author.
This is my way of giving back a little something to the freeware/shareware
community that has given me so much in the past.  Feel free to list me in
the credits, though!  ;-)

     Disclaimer:  The author makes no claims as to the fitness or suitability
of any part of this product for any particular purpose.  If you fry a hard
drive or something while using HOMONLIB, or it doesn't work like you think
it's supposed to (or at all), it's not my fault.

Contacting the author:

     If you have questions, problems or suggestions regarding HOMONLIB, feel
free to send me E-mail via CompuServe at 74220,2344.  At this time, I am not
accepting E-mail via the internet because it costs me money.


ASSUMPTIONS/CONVENTIONS:

     I assume you know DOS.  I assume you know how to use the QB editor.  I
assume you know what BC, LINK, and LIB.EXE do.  If you are familiar with
their command line usage, great!  You can alter and recompile/relink the
library to your heart's desire.  If not, you can load the QLB when you start
the editor and compile/link your programs from the RUN menu.

     I assume that you have the following directory structure on your hard
drive:

          C:\QB45             Contains your binary files, like QB.EXE
          C:\QB45\LIB         Contains your LIBs & QLBs, like QB.LIB
          C:\QB45\INCLUDE     Contains your include files, like QB.BI

If these path assumptions are incorrect, just substitute the appropriate
drive or directory where applicable.

     I use the words "function", "sub", and "procedure" liberally throughout
this file and the source code comments.  I did not attempt to standardize my
usage of these words.  They are used interchangeably, and basically all mean
the same thing (unless, of course, referring to the return value of a proper
FUNCTION).

     When referring to function (see above) names that are part of HOMONLIB,
they will be followed with an empty pair of parentheses and have the first
letter of each "word" capitalized:

                            SetCursor()

When referring to a QB function or reserved word, it will be typed in all
caps.  Constants defined in an include file will also appear in all caps:

                            PRINT    (QB)
                            MAXPARM  (Constant)

If you notice any inconsistencies, I am sorry.  This library was developed
over a long period of time and a few comments may have escaped my review.


PREPARATION FOR USE:

     Copy the original ZIP file to a diskette for safekeeping if you haven't
done so already.

     I suggest you create a subdirectory to keep all the HOMONLIB files
separate from your other projects.  I have mine set up as a subdirectory of
the LIB directory:

     C:\QB45\LIB\HOMONLIB

Copy all the source files (*.BAS) to this new directory.  Copy all the make
files to this directory as well (*.BMK, LMK, LNK).  Copy all the include
files (*.INC) to your INCLUDE directory.  Copy HOMONLIB.LIB & QLB to the LIB
directory.  The BMAKE executable should be copied to the C:\QB45 directory.
The text files should be placed wherever you find it convenient to access
them.  I recommend printing the HOMONREF.TXT and QUICKREF.TXT files.

     In the editor, use the Set Paths option under the Options menu to tell
QB about your directory structure & where to find certain kinds of files if
you have not done so already.

     You can now load the QuickLibrary when you start the editor and begin
using the new functions right away.  The declarations and instructions for
each individual procedure's use are in the source files themselves.  All
these declarations and comments are reprinted (in alphabetical order) in
HOMONREF.TXT.

To load the QuickLibrary at startup:  QB /L HOMONLIB.QLB [YOURPROG.BAS]


USAGE NOTES:

     While browsing through the source code, you will notice that a lot of
the procedures take an integer array called parm() as an argument.  This
array is used to hold your screen color settings and other information.

     I suggest you declare it as SHARED or COMMON SHARED in the main module
of the application that is to use HOMONLIB.  To do so, the following lines
(at least) should appear in your program:

               ' $INCLUDE: 'PARM.INC'
               DIM SHARED parm(1 TO MAXPARM)

By making the array shared, you don't need to explicitly pass it from
procedure to procedure in your program - only to the library functions.

     You can either hard-code the various color assignments or allow the user
to customize them through the use of the ColorSet() function.  You can then
save these settings to some sort of INI or DAT file to be read at startup.

     More information about using the parm array can be found in the SUBs and
FUNCTIONs that use it, and in the PARM.INC file itself.


     HOMONLIB is very granular.  This means that if you only use a few parts
of it, only those parts are placed into your final EXE.  HOMONLIB is also
very inter-dependent.  Many of the functions rely upon each other.  Keep this
in mind if you alter any of the source to suit your needs.  If you change
something drastically enough, other functions that rely on it may fail to
work.

     I have also tried to make the library as modular as possible.  When you
pass variables to the procedures, they don't get inadvertantly changed unless
that was the purpose to begin with.  Any functions that change their
arguments are explicitly noted as doing so in the comments.

     Whenever a function needs to change a color or alter the screen in some
way, they make every effort to put it back the way it was prior to calling
the function.  The abundance of set/get functions in the library make this
possible.  Keep in mind that all the functions that take parm() as an
argument assume that the color is currently set to parm(FGN), parm(BGN) and
will restore this setting upon exit.  Any exceptions are noted in the
comments.

     To rebuild the library if you make changes to it, run BMAKE HOMONLIB at
the DOS prompt in the C:\QB45\LIB\HOMONLIB directory (This assumes your \QB45
directory is listed in your PATH statement).  If you add or remove any
modules from the library, be sure to update the BMK & LMK files.  The "LMK"
extension is just something I made up - it stands for "Library MaKe file".
You will also need to modify these files if your directory structure is
different than the assumed structure noted above.  For more information about
BMAKE, see its accompanying text file.

-----------------------------------------------------------------------------

     I have spent a lot of years developing the code and programming style
that went into HOMONLIB.  I sincerely hope you find it useful or educational.
I really enjoy programming in BASIC, and am pleased to see that it is gaining
wider recognition as a viable, modern programming language.

     Have fun and ENJOY!!!

     Raymond W. Marron
     HOMONCULOUS PROGRAMMING


MANY THANKS/SUGGESTED READING:

     I would like to thank Ethan Winer of Crescent Software for making his
book "BASIC Techniques and Utilities" available to the public.  It contains
invaluable information on the inner workings of the BASIC language.  If you
want to learn more about compiler and linker options, this is the book for
you.  You can find this on CompuServe as "WINER.ZIP".

     I would also like to thank Fairchild Computer Services for providing the
basis of my Dir$() function.  This is another gem that I found on CompuServe,
and another example of the generous spirit of the programming community.  You
can find this code under the name of "DIR.ZIP" and it comes with some other
very nice programs and examples.


*** End of README.TXT