************
*  Logger  *
************

Copyright 1995
Prime Time Programming
Written by Robert Vivrette


Ok, it has happened to all of us at one time or another... You are writing your
Windows program and you need to see the value of some variable, or find out when
you are getting into a particular section of code. Most programmers resort to
use of the MessageBox procedure, but this option disturbs the normal flow of the
program and looks ugly too... Also, to display a few variables together, you
have to concatenate them together into a PChar before passing them to
MessageBox. Yuck!

Out of this frustration was born Logger. My purpose in developing Logger was to
find a simple way to log debugging information during execution of a program in
such a way that it did not disturb the programs normal flow.

Before I go any further, I want to make clear that this unit is being
distributed as "Shareware". The idea is that you have 30 days to evaluate this
unit before you must decide to send me the shareware fee or stop using it. I
have done nothing to this unit that would hamstring it in any way, but users who
register Logger will receive a number of benefits, so please read the shareware
notice at the bottom of this document.

To use Logger, simply include a reference to Logger in the USES section of your
program. Then whenever you want to log a debugging message, you simply call the
Log() procedure and pass in the message you want to display (as a PChar). That
is all there really is to it! The dialog is created automatically the first time
it is referenced, and it is cleaned up automatically when the program is
finished.

* * * * * * * * * * * * * * * * * * IMPORTANT * * * * * * * * * * * * * * * * *

Since I wanted to have the ability to display or not display the Logger, there
is a boolean variable called LogShow that initially defaults to False (i.e. you
do NOT initially see the log dialog box). If you want to programatically control
the display of the Logger, simply call ShowLog or HideLog at appropriate
locations. These procedures set the value of the LogShow variable and also
explicitly show or hide the Logger dialog box. In addition, if the program you
are running has the parameter "LOG" anywhere on its command-line (case
insensitive), the Logger will initially start VISIBLE. Since the LogShow
variable defaults to False (i.e. hidden), the only way to make it visible is to
do one of the following:

      1. Include "LOG" on the program's command-line,
      2. Call the procedure ShowLog,
      3. Set LogShow to TRUE before your first call to Log()

I established the visibility state of the program in this way so that a program
could have debugging messages throughout it, and the programmer would only see
them when he wanted to (typically by including ShowLog at the top of the
program, or by putting "LOG" on the command line). Then to see the program as
it would behave normally, simply remove ShowLog or don't include the word "LOG"
on the command line. This means that you can have a program filled with
debugging messages that is all compiled and distributed to a few users. If they
are having problems, you can tell them to put the word "LOG" on the command
line and you instantly have information that can help the user track down the
problem! With the SaveLog procedure included when you register Logger, your
program can record the contents of the log whether it is visible or not so you
will have a record of what your program did.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

You also have the ability to define where the Logger dialog box will be created
and what its caption will be. By default, the dialog will be created in the
upper right corner of the screen, and have the caption "Logger". The dialog
caption is stored in a PChar called LogTitle (maximum of 60 characters). To
change it to "Employee Program Log" for example, you would do the following:

            StrCopy(LogTitle,'Employee Program Log');

You should do this before your first call to Log() or before calling ShowLog.
Once the dialog is created, its caption will not change.

To control the position of the Logger dialog box, I use a byte variable called
LogLoc which holds a combination of the following bitmasked values.

     Horizontal position:   locCenterHorz, locRight & locLeft
     Vertical position:     locCenterVert, locTop & locBottom

If you wish to change its location, simply set the LogLoc value to a combination
of one Horizontal position value and one Vertical position value added together.
For example, to have the box in the center of the right edge of the screen, you
would do the following:

     LogLoc := locCenterVert + locRight;

I have already set up some common values for LogLoc as follows:

     locCenter       = locCenterHorz + locCenterVert;
     locTopLeft      = locTop + locLeft;
     locTopRight     = locTop + locRight;
     locBottomLeft   = locBottom + locLeft;
     locBottomRight  = locBottom + locRight;

The Logger starts out initially cleared (except for a small reminder that it is
a shareware product). If at anytime you wish to clear Logger's list box, simply
call ClearLog.

In addition, even though Logger automatically cleans up after itself, you may
wish to destroy the Logger dialog prior to the end of the program. To do this
simply call DestroyLog. This is completely optional... I rarely use it, but
wanted to include it anyway.

You can also turn off information logging if you wish. This is controlled by a
Boolean variable called LogOn (initially set to TRUE). If you set LogOn to
FALSE, any Log() calls from that point will be ignored and not logged. To turn
logging back on, simply set LogOn back to TRUE.

In case you ever get a "Version Type Mismatch" error for Logger when compiling
your program, it generally means that you have modified one of the basic windows
system units provided with BP. Logger uses WinProcs, WinTypes, ODialogs,
OWindows & Strings.

Ok, now down to the meat... In order to give the user the greatest flexibility,
I created several ways to log messages to the Logger. Below is a list of these
various methods and their calling syntax:



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

  PROCEDURE Log(A: PChar);

     This will log a single PChar into the list box. Some examples:

     Log('Beginning the print routine');
     Log(MyPCharVariable);

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

  PROCEDURE Log2(A,B: PChar);

     This will log 2 PChars into the list box. Some examples:

     Log2('The value of LastName is: ',LastName);
     Log2(FirstName,LastName);

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

  PROCEDURE Log3(A,B: PChar);

     This will log 3 PChars into the list box. Some examples:

     Log3('The user of this record is: ',FirstName,LastName);
     Log3(FirstName,LastName,SocialSecurity);
     Log3(InitialPChar,' has changed into ',CurrentPChar);

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

  PROCEDURE LogInt(A: PChar; B: LongInt);

     This will log a PChar followed by an integer value into the list box. An
     example:

     LogInt('LoopCounter=',LoopCounter);

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

  PROCEDURE LogReal(A: PChar; B: Real; Width,Decimals: Byte);

     This will log a PChar followed by a real value into the list box. The user
     can specify total width, and Decimal precision values to display the real
     value. Some examples:

     LogReal('Salary=',Salary,10,2);
     LogReal('CosineX=',CosineX,12,7);

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



In addition, I have included access to some other procedures that Logger
normally uses. They are:

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

  PROCEDURE PlaceWindow(TheWnd: HWnd; Spot: Byte);

  This procedure will take any window (given its HWnd) and place it in location
  relative to the current screen size. I use this procedure to place Logger in
  various places on the screen, but you can also use it to place any other
  window or dialog box in your program. The "Spot" parameter is the bitwise
  operators discussed earlier in this document. For example, to place one of
  your dialog boxes in the center of the screen, simply do the following:

       PlaceWindow(MyDialog^.HWindow,locCenter);

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

  FUNCTION AParamIs(A: PChar): Boolean;

  This function determines whether a passed-in value is equal to any of the
  parameters on the programs command line. The AParamIs function is not case
  sensitive, and doesn't care where the parameter is. Logger uses this function
  to determine if you have specified "LOG" on the command line. For example, you
  might want to test something like this:

       DoPrintRoutine := Not AParamIs('NOPRINT');

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


Shareware Notice
----------------
This version of Logger is a shareware product. The shareware fee for Logger is a
measly $12. Users who send in their registration fee will receive back in the
mail a diskette containing the latest copy of Logger as well as all of the
source code.

The latest copy will include any enhancements that I have made to Logger since
posting this package as well as the added feature of being able to save the
content of the Logger listbox to a disk file (i.e. SaveLog('C:\MYLOG.TXT'); ).

If you wish to provide a copy of Logger to a friend for evaluation, please make
sure that it includes this document as well.


The Quasi-Legal Stuff
---------------------
The unit in this package is licensed, not sold to you, when you pay a Shareware
fee of $12.00 (US). You have 30 days to evaluate Logger before you must decide
to send the shareware fee or stop using it. The Logger Unit remains owned by
Prime Time Programming. The Logger Unit and documentation are Copyright 1995 by
Prime Time Programming, all rights reserved. Prime Time Programming accepts no
responsibility or liability for Logger or what it might do to your program so
you use it at your own risk.



If you wish to report any bugs or ideas for the next version of Logger, or if
you are sending in your shareware fee, you can reach me at the following:


Robert Vivrette, Owner
Prime Time Programming
PO Box 5018
Walnut Creek, CA  94596-1018


Fax: (510) 939-3775
CompuServe: 76416,1373
America Online: R5Rette
eWorld: Vivrette
