Assert

Navigation:  Appendices > Macro Language > Built-in Functions > All Functions (Alphabetical) >

Assert

Previous pageReturn to chapter overviewNext page

void = Assert(bCondition, sMessage, 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 :

 

bCondition

This is a boolean litteral or variable or expression. This is a condition that must be true for your macro to make sense. If this condition is true, then nothing happens. If this condition is false, then an error is generated., using the message contained in sErrorMessage.

sMessage

This is the text that will appear in the error message, whether it is simply a run-time message, or it causes the script to abort.

bAbortScript

If the value of bAbortScript is set to false then the failure of this assertion will simply abort the current macro and generate a run-time message which will be displayed in the Messages Window during diary generation. If the value of bAbortScript is set to true then the failure of this assertion will abort the current script and display a modal message with the context of the error (see example below).

 

 

 

Example :

 

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

 

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 assumtion 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 updated on 01-Nov-2016.
Topic URL: http://www.qppstudio.net/webhelp/index.html?assert.htm