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
==============================================================================