Personal and public use of my _Common Components_

In this post:

• Preface
• Managing the balancing act
  • Conditional Compile Arguments
  • Provisioning the flexibility
    • The ErrMsg interface procedure
    • The BoP/EoP interface procedures
  • The “Debugging Option”
• Comments

Managing the balancing act: Common Components designed for a best possible fit with my own VB-Projects using them but without bothering others with my way of using/integrating them. However, maintaining different code versions of a Common Component, one which I use in my VB-Projects and another ‘public’ version is not worthwhile.

Preface

My Common Component’s aim is to function as autonomous as possible, i.e. not requiring any additional installed component. In other words, any additional component I use with/for them needs to remain optional.

Managing the balancing act

1. Any additional component, i.e. another Common Component remains optional by means of Conditional Compile Arguments indication that a component is installed/available and should be used.
2. “Interface” procedures call optional components only when indicated installed/available.

Conditional Compile Arguments

Cond. Comp. Arg.	Purpose
mTrc = 1	Indicates that the _Common VBA Execution Trace Service_ (mTrc) is installed and will actively be used
clsTrc = 1	Indicates that the _Common VBA Execution Trace Service_ (clsTrc) is installed and will actively be used
mMsg = 1	Indicates that Common VBA Message Service (mMsg/fMsg) is installed so that the mMsg.Dsply service can be used as alternative to the VBA.MsgBox
mErH = 1	Indicates that the Common VBA Error Services (mErH) is installed which is able to display the ‘path-to-the-error’

Provisioning the flexibility

The ErrMsg interface procedure

A copy of the ErrMsg “interface” procedure is used in each Common Component for the display of an error message with the following options:

• a debugging option button when the Conditional Compile Argument ‘Debugging = 1’

• an optional additional “About:” section when the err_dscrptn argument has an additional string concatenated by two vertical bars (

  )

• the display of the error message by means of the Common VBA Message Service when installed and active (Conditional Compile Argument MsgComp = 1)
• the display of the possibly most comprehensive and well designed error message by the Common VBA Error Service when installed (Conditional Compile Argument MsgComp = 1)
• the display of an error message by means of the VBA.MsgBox when neither the Common VBA Message Service nor the Common VBA Error Service is installed.

Public Function ErrMsg(ByVal err_source As String, _
              Optional ByVal err_no As Long = 0, _
              Optional ByVal err_dscrptn As String = vbNullString, _
              Optional ByVal err_line As Long = 0) As Variant
' ------------------------------------------------------------------------------
' Universal error message display service. Obligatory copy Private for any
' VB-Component using the common error service but not having the mBasic common
' component installed.
'
' Uses: AppErr  For programmed application errors (Err.Raise AppErr(n), ....)
'               to turn them into a negative and in the error message back into
'               its origin positive number.
'
' W. Rauschenberger Berlin, June 2023
' See: https://github.com/warbe-maker/VBA-Error
' ------------------------------------------------------------------------------
#If ErHComp = 1 Then
    '~~ When Common VBA Error Services (mErH) is availabel in the VB-Project
    '~~ (which includes the mMsg component) the mErh.ErrMsg service is invoked.
    ErrMsg = mErH.ErrMsg(err_source, err_no, err_dscrptn, err_line): GoTo xt
    GoTo xt
#ElseIf MsgComp = 1 Then
    '~~ When (only) the Common Message Service (mMsg, fMsg) is available in the
    '~~ VB-Project, mMsg.ErrMsg is invoked for the display of the error message.
    ErrMsg = mMsg.ErrMsg(err_source, err_no, err_dscrptn, err_line): GoTo xt
    GoTo xt
#End If
    '~~ When neither of the Common Component is available in the VB-Project
    '~~ the error message is displayed by means of the VBA.MsgBox
    Dim ErrBttns    As Variant
    Dim ErrAtLine   As String
    Dim ErrDesc     As String
    Dim ErrLine     As Long
    Dim ErrNo       As Long
    Dim ErrSrc      As String
    Dim ErrText     As String
    Dim ErrTitle    As String
    Dim ErrType     As String
    Dim ErrAbout    As String
        
    '~~ Obtain error information from the Err object for any argument not provided
    If err_no = 0 Then err_no = Err.Number
    If err_line = 0 Then ErrLine = Erl
    If err_source = vbNullString Then err_source = Err.source
    If err_dscrptn = vbNullString Then err_dscrptn = Err.Description
    If err_dscrptn = vbNullString Then err_dscrptn = "--- No error description available ---"
    '~~ About
    ErrDesc = err_dscrptn
    If InStr(err_dscrptn, "||") <> 0 Then
        ErrDesc = Split(err_dscrptn, "||")(0)
        ErrAbout = Split(err_dscrptn, "||")(1)
    End If
    '~~ Type of error
    If err_no < 0 Then
        ErrType = "Application Error ": ErrNo = AppErr(err_no)
    Else
        ErrType = "VB Runtime Error ":  ErrNo = err_no
        If err_dscrptn Like "*DAO*" _
        Or err_dscrptn Like "*ODBC*" _
        Or err_dscrptn Like "*Oracle*" _
        Then ErrType = "Database Error "
    End If
    
    '~~ Title
    If err_source <> vbNullString Then ErrSrc = " in: """ & err_source & """"
    If err_line <> 0 Then ErrAtLine = " at line " & err_line
    ErrTitle = Replace(ErrType & ErrNo & ErrSrc & ErrAtLine, "  ", " ")
    '~~ Description
    ErrText = "Error: " & vbLf & ErrDesc
    '~~ About
    If ErrAbout <> vbNullString Then ErrText = ErrText & vbLf & vbLf & "About: " & vbLf & ErrAbout
    
#If Debugging = 1 Then
    ErrBttns = vbYesNo
    ErrText = ErrText & vbLf & vbLf & "Debugging:" & vbLf & "Yes    = Resume Error Line" & vbLf & "No     = Terminate"
#Else
    ErrBttns = vbCritical
#End If
    ErrMsg = MsgBox(Title:=ErrTitle, Prompt:=ErrText, Buttons:=ErrBttns)
xt:
End Function

The BoP/EoP interface procedures

A copy of the below procedures in each Common Component keeps the installation/availability of the Common VBA Error Services and the Common VBA Execution Trace Service optional. See how these procedures (the corresponding code lines respectively effects the display of the path to the error displayed when the Common VBA Error Services is installed.

Public Sub BoP(ByVal b_proc As String, _
      Optional ByVal b_args As String = vbNullString)
' ------------------------------------------------------------------------------
' Common 'Begin of Procedure' interface serving the 'Common VBA Error Services'
' and - if not installed/activated the 'Common VBA Execution Trace Service'.
' Obligatory copy Private for any VB-Component using the service but not having
' the mBasic common component installed.
' ------------------------------------------------------------------------------
#If ErHComp = 1 Then          ' serves the mTrc/clsTrc when installed and active
    mErH.BoP b_proc, b_args
#ElseIf XcTrc_clsTrc = 1 Then ' when only clsTrc is installed and active
    Trc.BoP b_proc, b_args
#ElseIf XcTrc_mTrc = 1 Then   ' when only mTrc is installed and activate
    mTrc.BoP b_proc, b_args
#End If
End Sub

Private Sub EoP(ByVal e_proc As String, _
       Optional ByVal e_args As String = vbNullString)
' ------------------------------------------------------------------------------
' Common 'Begin of Procedure' interface serving the 'Common VBA Error Services'
' and - if not installed/activated the 'Common VBA Execution Trace Service'.
' Obligatory copy Private for any VB-Component using the service but not having
' the mBasic common component installed.
' ------------------------------------------------------------------------------
#If ErHComp = 1 Then          ' serves the mTrc/clsTrc when installed and active
    mErH.EoP e_proc, e_args
#ElseIf XcTrc_clsTrc = 1 Then ' when only clsTrc is installed and active
    Trc.EoP e_proc, e_args
#ElseIf XcTrc_mTrc = 1 Then   ' when only mTrc is installed and activate
    mTrc.EoP e_proc, e_args
#End If
End Sub

The “Debugging Option”

See the Used Common Components_ section in the README of the _Common VBA Error Services for how the option is displayed depending on the used (or not used) Common Components.

Comments

Comments are welcome. I apologize for the fact that commenting requires a login to GitHub. This seems to be the only way to keep away spammers.