void = Assert(bCondition, sErrorMessage, bAbortScript)

 

Use the Assert macro function to verify if bCondition is true, and if not then generate your own error messages during the execution of a Macro. This function is a shortcut equivalent to the use of the RaiseError function :

if not bCondition
   RaiseError(sMessage, bAbortScript)
endif

This function takes 3 parameters :

 

 

 

Examples

 

bAbortScript = false

 

The following call to Assert with bAbortScript being false,

Assert(nInputValue in [1..7], 'Weekday is not in range of 1-7', false)

would then add the following messages to the diary generation messages dialog, without interrupting the script execution.

 

 

bAbortScript = true

 

The following call to Assert with bAbortScript being true,

Assert(nInputValue in [1..7], 'Weekday is not in range of 1-7', true)

would then immediately display the following dialog, with detailed information about the context of the message, and then abort script execution.

 

 

Note that, as with other void functions, you do not need to assign the result of this function to any variable.

 

Why use Assertions ?

 

Generally assertions are used wherever, in a macro, there is a fundamental condition that must be true or else the macro does not make sense anymore. More specifically, there are 2 specific cases where assertions are often used.

 

To validate the value of input variables

 

When you write a macro that uses input variables, you can be assured that your macro will receive input parameters of the right type. However, your macro may only make sense for certain values of that type. Assertions allow you to place checks in your macro to ensure that input values make sense.

 

For example, if an input value is meant to be the month number, you may want to use :

input
    nMonthNumber
var
begin
    Assert(nMonthNumber in [1..12], 'Month numbers are 1-12', true)
    // if we get to here then the value of nMonthNumber is within 1-12
    ...
end

To safely get rid of compiler warnings

 

When you write a macro that uses more than one global variable, you often initialize all the global variable at once, the very first time the macro is executed. Sample code may look as follows:

global
    nCurLeftPage nDate1 nDate2 nDate3 nDate4
var
    bSpreadChange bFoundIt
begin
    if not IsInitialized(nCurLeftPage)     
        nCurLeftPage = 1
        nDate1 = 0
        nDate2 = 0
        nDate3 = EncodeDate(n_TokenYear, 1, 1)
        nDate4 = 0
    else
        // use nDate1 nDate2 nDate3 nDate4 
        ...
    endif
end

The problem with the code above is that code in the else branch will cause 4 warnings to be generated by the macro compiler, warning that nDate1 nDate2 nDate3 nDate4 may not have been initialized, because it does not see any calls to the function IsInitialized with these variables passed as parameters. The solution is to rewrite the above as :

global
    nCurLeftPage nDate1 nDate2 nDate3 nDate4
var
    bSpreadChange bFoundIt
begin
    if not IsInitialized(nCurLeftPage) 
        nCurLeftPage = 1
        nDate1 = 0
        nDate2 = 0
        nDate3 = EncodeDate(n_TokenYear, 1, 1)
        nDate4 = 0
    else
        Assert(IsInitialized(nDate1), '', true)    
        Assert(IsInitialized(nDate2), '', true)    
        Assert(IsInitialized(nDate3), '', true)    
        Assert(IsInitialized(nDate4), '', true)    
        // use nDate1 nDate2 nDate3 nDate4 
        ...
    endif
end

Note that this gets rid of the compiler warnings safely. If any of these 4 variables is not initialized by the time execution enters the else branch an error will be generated.

 

Using the Assert function is ideal if you only want to verify that a unique basic assumption is true. Otherwise, if there are many possibilities that are addressed in code and you want an error if none of these is followed, then you should use the RaiseError function. If you want a run-time message to be generated, without causing any error condition, then use the LogMessage function.

 

---

Topic 174270, last updated on 19-Apr-2020