;; 
;;=====================================================================================----- 
;; 
;;FUNCTION       fMsg() 
;; 
;;ACTION         Consolidated message display/logging function 
;; 
;;AUTHOR         Glenn Barnas 
;; 
;;VERSION        1.2  - 2014/12/27 
;; 
;;HISTORY        1.0  - 2010/09/15 - Initial Release 
;;               1.1  - 2013/03/01 - add overwrite option to Mode 
;;               1.2  - 2014/12/27 - add Err_Log_ support, Use of Open/Writeline/Close 
;; 
;;SYNTAX         fMsg(Msg, LMsg, Nl, Mode, Opt, R, C) 
;; 
;;PARAMETERS     Msg - REQUIRED - String 
;;               - message to display 
;; 
;;		 LMsg - OPTIONAL - String 
;;               - message to log. Defaults to Msg if not specified 
;; 
;;		 Nl - OPTIONAL - Boolean 
;;               - Suppress Newline flag 
;; 
;;		 Mode - OPTIONAL - Binary 
;;               - Control function 
;;                      64 = Write to file defined by $ERR_LOG_ instead of $MSG_LOG_ 
;;			32 = Overwrite output file 
;;			16 = Log Only - suppress screen display 
;;			 8 = Terminate processing, exit with $_Ec 
;;			     Overrides Debug mode! 
;;			 4 = Debug Mode - only display if DEBUG is active 
;;			 2 = Timestamp the screen message 
;;			 1 = Suppress Log Timestamp 
;; 
;;		 Opt - OPTIONAL - Number 
;;		 If Terminate mode, this is the Error code to exit with. 
;;		 If Debug mode, the Debug level required to display debug messages 
;;               All other modes, this value is returned as the exit code. 
;; 
;;		 R, C - OPTIONAL - Number 
;;               - Row/Column to display at 
;; 
;;REMARKS        A single function to handle common logging requirements. 
;;		 Log messages are timestamped unless suppressed. 
;;		 Screen messages are not timestamped unless requested. 
;;		 The Opt value is returned as an exit code if Mode 4 (debug) or 
;;		 8 (terminate) are not set. This allows fMsg to display an error 
;;		 code and preserve the error number. 
;; 
;;RETURNS        Nothing 
;; 
;;DEPENDENCIES   Authority over RedirectOutput as backup to available file handles 
;; 
;;TESTED WITH    W2K, WXP, W2K3, W2K8, Vista, Win7 
;; 
;;EXAMPLES       fMsg('Process start')		; simple message 
;;		 fMsg('Startup', '100')		; message to screen, code to log 
;;		 fMsg($Msg, , 1)		; message, suppress CRLF 
;;		 fMsg($Msg, , 0, 1)		; complete message, suppress timestamp in log 
;;		 fMsg($Msg, , 0, 16)		; only write to log file 
;;		 fMsg($Msg, , 0, 20)		; only write to log file if DEBUG is true 
;;		 fMsg($Msg, , 0, 8, 2)		; Fatal error - Quit with status "2" 
;;		 $ = Function($arg)		; display status, preserver @ERROR value 
;;		 fMsg('function returned' + @SERROR, , 0, 0, @ERROR) 
;  
Function fMsg($_Text, OPTIONAL $_LText, $_Nl, $_Mode, $_Opt, $_R, $_C)
 
  Dim $_
  Dim $_Quit						; abend mode flag 
  Dim $_LTs, $_DTs					; log and screen timestamp vars 
  Dim $_Overwrite					; overwrite file if true 
  Dim $_LogFile						; name of output log file 
  Dim $_Fh						; file handle 
 
  $_LogFile = $MSG_LOG_					; set log file to output 
  $_Nl      = IIf(Val($_Nl), '', @CRLF)			; default to CR/LF 
  $_Mode    = Val($_Mode)				; insure numeric 
  $_Fh      = 0
  
  $_LTs = @DATE + ' ' + @TIME + ':       '		; log text is timestamped by default 
  $_DTs = ''						; display text is not timestamped 
 
  
  If ($_Mode & 64)					; request write to file defined by $ERR_LOG_ 
    If Not $ERR_LOG_ And $MSG_LOG_
      $_LogFile = $MSG_LOG_				; write to MSG LOG if ERR_LOG is not defined 
    Else
      $_LogFile = $ERR_LOG_
    EndIf
  EndIf
 
  If Not $_LText
    $_LText = $_Text					; default log textto display text 
  EndIf							; if not specified 
 
  $_Overwrite = 0					; set output to Overwrite 
  If ($_Mode & 32)
    $_Overwrite = 1
  EndIf
 
  If ($_Mode & 8)					; ABEND mode 
    $_Mode = 0						; clear other options 
    $_Quit = IIf($_Opt = '', 1, $_Opt)			; set exit code (default=1) 
    $_Quit = Int($_Quit)				; Convert to int 
    If $_Quit <> 0
      $_LTs = @DATE + ' ' + @TIME + ':-ABEND-'		; log text is timestamped, error exit 
      $_Dts = @DATE + ' ' + @TIME + ':-ABEND-'		; screen text is timestamped, error exit 
    Else
      $_LTs = @DATE + ' ' + @TIME + ':-EXIT- '		; log text is timestamped, non-error exit 
      $_Dts = @DATE + ' ' + @TIME + ':-EXIT- '		; screen text is timestamped, non-error exit 
    EndIf
    $_Nl = @CRLF					; always output CR/LF 
  EndIf
 
  If ($_Mode & 4) And Not $_Quit			; DEBUG mode 
    $_Opt = IIf($_Opt, $_Opt, 1)			; set debug level to match 
    If $DEBUG = 0 Or ($DEBUG > 0 And $_Opt > $DEBUG)	; Exit if not debug or debug > level 
      Exit 0						; return immediately with no output 
    EndIf
    $_LTs = @DATE + ' ' + @TIME + ':-DEBUG-'		; log text is timestamped 
    $_DTs = '-DEBUG-'					; defin DEBUG prefix 
    $_Nl = @CRLF					; always output CR/LF 
    $_Mode = $_Mode & 18				; clear other options  
    $_Opt = 0						; prep to exit success 
  EndIf
 
  If ($_Mode & 2)					; screen text is timestamped 
    $_DTs = @DATE + ' ' + @TIME + ':' + $_Dts		; append prior message 
  EndIf
 
  If ($_Mode & 1)					; screen text is timestamped 
    $_LTs = ''						; Clear timestamp 
  EndIf
 
 
  ; Output the message 
  If Not ($_Mode & 16)					; screen output enabled 
    If $_R And $_C At($_R, $_C) EndIf			; optionally position the cursor 
    $_DTs $_Text $_Nl					; Optional timestamp, text, optional NL 
  EndIf
 
  ; write to log if defined - will Open/Write/Close if filehandle is available, 
  ; otherwise uses RedirectOutput() to insure logging is done 
  If $_LogFile
    $_Fh = FreeFileHandle()
    If $_Fh
      If $_Overwrite Del $_LogFile EndIf		; delete prior file if set 
      $_ = Open($_Fh, $_LogFile, 5)			; open for append 
      $_ = WriteLine($_Fh, $_LTs + $_LText + $_Nl)	; write the data 
      $_ = Close($_Fh)					; close the file 
    Else
      $_ = RedirectOutput($_LogFile, $_Overwrite)
        $_LTs $_LText $_Nl				; Optional timestamp, text, optional NL 
      $_ = RedirectOutput('')
    EndIf
  EndIf
 
  If $_Quit
    Quit $_Quit						; terminate script 
  Else
    Exit $_Opt						; preserve any error code 
  EndIf
 
EndFunction