SQABasic "CustomLogUtilities" Library

 MODULE DESCRIPTION:

      This module is used to implement project specific, or site specific,
      logging that is intended to either enhance or replace the built-in logging
      provided by the Core framework.  The built-in logging is primarily handled
      by the LogUtilities library.

      Note that the static Core framework has no way of dynamically accessing or
      even recognizing custom log utilities implemented by the developer except
      by calling the predefined hook functions in this library. An added
      benefit to the developer is that they can populate the SBH header
      files with their own variables, constants, user-defined types, and
      function declarations for their custom logging functions.  These would
      then automatically get included by any library that includes the main
      DDE header--DDEngine.SBH. It prevents developers from having to add
      their own custom include(s) for information they stick in these headers.

      The developer can implement their routines in this file, or they can call
      into any number of other files.

      Note, however, that the namespace for public routines and
      other public items is shared with the Core framework.  So you cannot
      duplicate the name of any public item or routine in your custom libraries.


Declarations Constants Global Variables User-Defined Types Routine Details

User Dependencies:

(stuff the developer's library/script $INCLUDES at compile time.)
(Note: The order of items may matter and may be different for your code.)

Internal Dependencies:

(stuff this library needs at compile time.)

Exported Declarations

Function CustomDDELogInitialization  BasicLib CustomLogUtilities 
Function CustomDDELogMessage     BasicLib CustomLogUtilities 
Function CustomDDELogFinalization  BasicLib CustomLogUtilities 

Constants



    (none)

Globals


    (none)

User-Defined Types



    (none)

Routine Details



  Function CustomDDELogInitialization (fac as LogFacility) As Integer

 DESCRIPTION:

      Used to enhance existing InitLogFacility functionality.
      The framework will call this "hook" after completing default initialization.
      This function can add initialization information sent to the logs
      and/or initialize or write to custom logs maintained by the user.


 PARAMETERS:

      fac         LogFacility sent with the message.

 RETURNS:

       0          (normal)
      -1          This is the standard DDE error code for Log Initialization errors.
                  The DDE also reserves codes -99 thru +99.
                  Any other code may be returned from CustomDDELogInitialization.

 ERRORS:

      (none)


 Orig Author: Carl Nagle
 Orig   Date: JUN 22, 2002
 History:

      JUN 22, 2002    Original Release




  Function CustomDDELogMessage (fac as LogFacility, msgType as Integer,
                                msgText as String, msgDescription as String
                               ) As Integer

 DESCRIPTION:

      Used to enhance or replace existing DDE LogMessage functionality.
      The DDE will call this "hook" prior to logging each message.  This
      function can intercept and enhance existing logging, write to additional
      custom logs maintained by the user, or completely bypass DDE logging
      to use a custom logging solution.

      Upon exit, this routine must return an appropriate value to instruct
      the DDE to continue or bypass normal logging.  By default, this routine
      allows normal logging to continue.


 PARAMETERS:

      fac         LogFacility sent with the message.

      msgType     integer of type of message we are logging.
                  (see LogUtilities CONSTANTS MessageType identifiers)
                  The DDE will have already converted this to GENERIC_MESSAGE if no
                  msgType was passed to LogUtilities.

                  Custom message types are not prevented and will be ignored by the core DDE
                  implementation.  Your custom logging must handle any custom message types
                  or no log output will be produced for that message.

                  Consult the LogUtilities documentation for the msgType values already
                  reserved for the core DDE.  These should be Integer values 0 thru 5000.

      msgText     string text of message sent with the LogFacility.

      msgDescription  additional descriptive text for the message.  This parameter is
                      optional for the core DDE and will have already been converted to
                      an empty string if it was not provided.


 RETURNS:

       LU_NORMAL_DDE_LOGGING          (default) allow normal DDE logging to continue
       LU_BYPASS_DDE_LOGGING          bypass normall DDE logging


 ERRORS:

      (none)


 Orig Author: Carl Nagle
 Orig   Date: JUN 22, 2002
 History:

      JUN 22, 2002    Original Release




  Function CustomDDELogFinalization (fac as LogFacility, finalize as Integer) As Integer

 DESCRIPTION:

      Used to enhance or replace existing DDE CloseAllLogs functionality.
      The DDE will call this "hook" prior to closing all file-based logs
      associated with the LogFacility passed in.  This function can intercept
      and enhance existing finalization, write to additional custom
      logs maintained by the user, or completely bypass DDE finalization
      to use a custom solution.

      Upon exit, this routine must return an appropriate value to instruct
      the DDE to continue or bypass normal finalization.  By default, this routine
      allows normal finalization to continue.


 PARAMETERS:

      fac         LogFacility sent with the message.

      finalize    1 instructs routine to write extra finalization text to
                  the log.
                  0 instructs the routine to only write the closing
                  date/time stamp.

                  These finalize values are used by the default DDE routines.  Your
                  custom routines may choose to ignore these values or react to
                  different values.


 RETURNS:

       LU_NORMAL_DDE_LOGGING          (default) allow normal Log Close operations.
       LU_BYPASS_DDE_LOGGING          bypass normal Log Close operations.

 ERRORS:

      (none)


 Orig Author: Carl Nagle
 Orig   Date: JUN 22, 2002
 History:

      JUN 22, 2002    Original Release


Copyright (C) SAS Institute
GNU General Public License: http://www.opensource.org/licenses/gpl-license.php 
==============================================================================