View source for Check Attribute

The Check attribute contains an expression tests the validity of the result of a variable, providing a way to catch potential errors in your model through sanity checks.  It can also be used to validate user input.

== Viewing the Check Attribute ==

By default, the Check attribute does ''not'' show up in the object window.  To turn it on, make sure you are in edit mode, then go to the '''Attribute dialog''' from the '''Object''' menu and double click on Check to place a check mark next to the Check attribute.  Notice that you can turn it on or off independently for variables and functions -- you may want to turn it on for both.  In the case of functions, it can be a convenient way to validate parameters.

[[Image:AttributeDialog.png]]

[[Image:ObjectWindowWithCheck.png]]

If you have not turned display of the Check attribute on in the attribute dialog, you can still access it from the dialog pane at the bottom of the diagram window.

== Specifying a Check ==

Within the Check attribute, you can use the variable's own identifier, or alternatively the keyword <code>Self</code> refers to the variable's value.  The check should evaluate to a boolean, e.g., 1 or 0, where 1 indicates that the value is acceptable and 0 indicates that the validation has failed.  For example:

:<code>Check: Self > 0 and Self <= 1</code>

When the variable is evaluated and this sanity check is violated, a warning such as the following displays:

[[Image:CheckWarning.png]]

=== Checking Array Values ===

When your check expression applies to an array value, depending on how you write it, the result of evaluating the check may itself be array valued.  In this case, a warning will be displayed if any element of the array fails the check.

=== Controlling the Warning Text ===

The default alert displayed when a Check fails displays the check expression itself.  You can control this text using an explicit call to the [[Error|Error function]] from within the check expression.  Calling [[Error]] is a second way to signal that the check has failed.  For example:

:<code>Check: if Sum(Self, I) <> 1 then Error("The values of P do not sum to 1 along I")</code>

[[Image:CheckWarning2.png]]

== Interactive cell-by-cell checks in edit tables ==

You can use the Check attribute to validate user input on a cell-by-cell basis as the data is entered.  When used in this fashion, cells that violate the check display with a red background, indicating a violation, and when a bad value is entered, a balloon appears pointing to the bad cell indicating that its value is bad.

Cell-by-cell checking is enabled only if the check attribute is set and does not operate over any table index.  For example, if the check attribute contains [[Sum]](Self, J) somewhere within its expression, and J is a table index, then cell-by-cell checking will be disabled.  [[Subscript|Subscripting]] and [[Slice|Slicing]] are consider to be operations over an index, so you cannot, for example, a comparison of the value in column 1 with the value in column 2 will disable cell-by-cell checking.  When cell-by-cell checking is disabled due to an operation over a table index, the check attribute is evaluated when the variable's result is computed, but the user does not receive immediate feedback.

The [[Error]] function can be used to customize the message for cell violations.  The values of table indexes can be referenced from a value context in a check expression, and when used in that fashion, contain the coordinate of the cell being checked.  You can therefore use the value of a table index in an [[IF]] clause -- e.g., 
:<code>If Date_Field = "First" and Self>Today() Then Error("First date cannot be in the future")</code>
:<code>Else if Date_Field = "Last" and Self<MakeDate(2020, 1, 1) Then Error("Last date must be before 2020")</code>

where ''Date_Field'' is a table index for the edit table.

== Disabling or Enabling Checks ==

The check attribute is evaluated when the ''Check value bounds'' preference is checked on the [[Preferences|Preferences dialog]].   Thus, alerts of violations of the check attribute can be suppressed by unchecking this preference, which otherwise is on by default.

== See Also ==

* A webinar recording on using the Check Attribute can be viewed at <code>[http://AnalyticaOnline.com/WebinarArchive/2008-07-17-Check-Attribute.wmv Check-Attribute.wmv]</code>.