Raising Errors in Data Macros to Cancel Events

User interface macros can interact heavily with the user's experience working with forms and reports. With user interface macros, you can display message boxes, open forms and reports, and dynamically change properties on a form. Data macros, on the contrary, are limited to the data layer and cannot interact with the user interface level. In a data macro, you cannot, for example, display a custom message box to the user and perform different steps based on how the user responds to your message. The only tool you can use in data macros to display information to the user is the RaiseError data action.

You can use the RaiseError data action whenever you need to force an error to occur and display a non-actionable message to the user manually. When you use the RaiseError action in a data macro, Access cancels the pending insert, update, or delete if it reaches this action during the macro execution. In the Before Change event that you've been building for the tblWeekDays table, we don't want to allow new records to be created in this table. In the previous section, you've already constructed the necessary If block conditional expression to determine when an update is occurring; now, you need to cancel the insert entirely if this condition is met. To do this, tab into the Add New Action combo box just below the If block conditional expression text, type the letter R, and then press Enter when Access displays RaiseError in the combo box. Note that this time, instead of clicking the combo box to drop down the list of actions and selecting one, we had you just type in the first letter of the action that you needed. (The macro design surface is flexible to allow you to use the mouse for selecting actions or just the keyboard if you prefer.) After you select RaiseError from the Add New Action combo box, Access displays the RaiseError data action inside the If block.

The RaiseError data action has two arguments-Error Number and Error Description. The Error Number argument is required. If you do not provide an Error Number, Access prevents you from saving your changes to the data macro. The number that you provide for the Error Number argument can be any whole number between the range of -2,147,483,648 to 2,147,483,647. We chose the number 102 for our example, so type 102 in the Error Number argument text box.

Note The error number that you choose for the RaiseError action is only for your benefit. You can choose, for example, to reuse the same error number for similar types of error conditions with other data macros or choose different error numbers for each data macro. Although you can use negative numbers for the error number, we recommend you use positive numbers. Most Access internal errors are negative numbers (except for 11 and 13, which are two positive internal error numbers), so it might be easier to distinguish your own error numbers from internal errors if you use positive error numbers.

The Error Description argument is the message displayed to the user if the RaiseError action is hit during execution of the data macro. You can type any custom message you want up to 256 characters in length. You can also use an expression for the Error Description if you want by typing the equals sign (=) as the first character. If you type an equals sign at the beginning of the Error Description argument, Access displays the Expression Builder button on the far right of the text box if you need assistance creating your expression. (We'll show you an example of using an expression in a RaiseError action later in this tutorial.) For our example, we'd like to display a simple message to the user informing them that they cannot enter new records into this table. Type the following message into the Error Description argument:

If you do not provide an error description in your RaiseError data action, Access displays a generic message if the RaiseError condition is hit. Although the message does indicate something went wrong, your users do not have sufficient information as to the exact cause of the error nor do they have sufficient information to fix the issue. We recommend that you always include a custom message to display to users when you use the RaiseError data action.

A very useful feature of the Logic Designer window is the ability to view Help information quickly no matter where you are. When you place your mouse over any elements on the macro design surface, Access displays a tooltip with specific Help information covering the program flow, data block, data action, or argument that you are currently on. Similarly, Access displays tooltips with Help information when you hover over the elements displayed in the Action Catalog. This feature is especially useful as you are learning your way around the Logic Designer.