Helix 7.0 introduces enhanced flexibility in handling errors that occur in sequences, allowing the collection designer to choose between three different behaviors. This technote documents those options, and also includes a discussion of the interactions between top-level, nested, and conditional sequences.
This technote discusses sequence handling in Helix 7.0; users of Helix 6.2 and prior should consult this technote instead.
For the sake of discussion, the following terminology is used to define the usage of sequences. These terms are not mutually-exclusive: a single sequence can be used in different places in a collection as a top-level sequence, a nested sequence, and a conditional sequence.
Top-level sequences are those that are initiated by a direct user action. A sequence placed in a user menu becomes a menu command that the user can select. A sequence placed in a command rectangle becomes a button on a view that the user can click. In both of these cases, the underlying sequence is referred to as a ‘top-level’ sequence.
Nested sequences are those that are embedded within other sequences. A sequence placed within another sequence executes its commands one time, then returns control to the original (top-level, nested, or conditional) sequence.
Conditional sequences are those that are initiated by conditions on a form at the time a sequence is initiated by clicking on a button. Conditional sequences are assigned as a property of a command rectangle. Every command rectangle must contain one top-level sequence, and may contain one or more conditional sequences.
Sequences can be used in conjunction with each other via nesting and conditional links. In any given situation, the aggregate of the top-level, nested, and conditional sequences is referred to as a sequence chain.
With the exception of detecting whether the Option key was down at the start of a sequence (see below), sequences do not inherit properties from sequences higher in the chain.
A sequence has five properties, as seen in the Inspector image shown on the right. The following sections describe each of these properties and their options.
Note that certain property settings may interact with other settings, so that changing one can have an unexpected — but completely consistent — effect on the other.
Also note that the ‘Custom message’ property is not displayed until the ‘Custom’ Message option is chosen.
Sequences can contain steps — such as ‘Print’ or ‘Delete’ — that typically require a dialog box to solicit user input (as in Print), or to warn the user of the danger of the operation (as in Delete). Sequences allow the collection designer to bypass these dialogs.
Show dialogs has three options: {Always, Optionally, Never}.
- A sequence set to ‘Always’ show dialogs will always solicit user input.
- A sequence set to ‘Optionally’ show dialogs will only solicit user input if the Option (Alt) key on the keyboard is held down at a specific time. (see below)
- A sequence set to ‘Never’ show dialogs will never solicit user input, even if the result is an error, as in the case of an ‘Import’ command whose pre-stored path is no longer valid.
The most powerful — and least understood — of these is the ‘Optionally’ show dialogs setting. The power of this option is that it bypasses the need for user input, while still allowing user input in situations where it is needed, such as the ‘Import’ command that needs to select a new file to import.
When a sequence set to Optionally (or Never) show dialog is executed, it completes dialogs using the values that were set the last time this dialog was presented. For example, when you open a view and choose print, you fill out a dialog that specifies the number of copies, the page range, etc. Those settings are captured in a ‘print record’ (a macOS property) that is used to ‘replay’ those settings when a sequence prints.
The status of the Option key is checked at two points during sequence execution: if the Option key is down when the top-level sequence is initiated, that status is retained and used for every sequence in the current sequence chain — including nested and conditional sequences — whose ‘Show dialogs’ property is set to ‘Optionally’.
The status of the Option key is rechecked at the beginning of each nested and conditional sequence. If a sub-level sequence is set to ‘Optionally’ show dialogs, and the Option key is down when that sequence begins, the steps within that sequence that have dialog boxes will display the dialog. When that sub-level sequence ends and control returns to the originating sequence, the status returns to its original state, assuming the Option key is not still held down.
When an error occurs in a sequence, the error message that is returned can be customized by the collection designer. Message option has three options: {Custom, Standard, None}
- A sequence whose error message is ‘Custom’ displays an error message created by the collection designer, regardless of the specific error that occurred.
- A sequence whose error message is ‘Standard’ displays an error message created by Helix, specific to the error that occurred.
- A sequence whose error message is ‘None’ display no error at all.
Note that “displays an error” in this context means that a Why? message is set and a System Beep is sounded.
When working in Design Mode, sequences that have a Custom error message also display the Standard error message, to aid in debugging the problem.
When a ‘Custom’ Message option is chosen, the ‘Custom message’ property is displayed. This is a text field into which the message is entered. This message replaces the Helix-generated error message for all errors that occur while this sequence is running.
New in Helix 7.0, the On error property gives the collection designer the ability to designate a specific error response for each sequence. On error has three options: {Continue, Stop, Return}
- A sequence set to ‘Continue’ will keep running, executing any subsequent steps in the sequence.
- A sequence set to ‘Return’ will stop running, so that any subsequent steps in the sequence are not executed. If the sequence is a nested sequence, its parent chain is stopped. If the sequence is a conditional sequence, execution continues with the next sequence in the chain.
- A sequence set to ‘Stop’ will stop running, so that any subsequent steps in the sequence are not executed. If the sequence is a nested or conditional sequence, the rest of the sequence chain is also stopped, halting the sequence entirely.
When a collection is updated to Helix 7.0, the “On error” property for all sequences is set to Return. This is also the default for all new sequences.
See the section ‘Comments on the History of Sequence Error Handling’ below for more information regarding the ancestry of these options.
In Helix, error messages are delivered by the Why? message mechanism. When an error occurs, a System Beep is sounded and the error message is updated with the latest error. Choosing Why? from the Help menu opens a dialog that displays this error.
When the ‘On error, open Why?’ property is checked, the error dialog is opened automatically, forcing the user to acknowledge it before going further.
[Editorial comment: It is amazing to us at QSA ToolWorks that the majority of end users we speak with have no knowledge of the Why? message. Network administrators would do well to educate their users about this valuable troubleshooting aid.]
It should be noted that if the ‘Message option’ is set to ‘None’ no error message is generated, so the ‘On error, open Why?’ property is ignored.
There are also two ‘special case’ sequence types that need to be understood:
- Tail Recursive
Adding a sequence as a step to itself creates a tail recursive sequence. Helix refers to these as ‘tail recursive’ sequences because the recursion step (i.e. the step where the sequence is embedded within itself) can only be the last step in the sequence.
A tail recursive sequence runs repeatedly until an error (user-initiated or other) stops it.
Tail recursion is useful in many ways. The simplest is an automated demo that loops repeatedly. More useful is a sequence that processes records one by one using a ‘Find Next’ step. Eventually the last record will be processed and ‘Find Next’ will return an error, causing the recursive sequence to exit.
Warning: a tail recursive sequence set to ‘continue’ on error can only be stopped by force quitting Helix.
- Terminal
New in Helix 7.0, terminal sequences are those that end by closing the collection (or the connection, in the case of Helix Client).
Two commands have been added to the list of Helix commands that can be added to sequences: Close Collection and Quit. Because the result of these commands is the end of database operations, they can only be the last step in a sequence.
Terminal sequences are useful in collections that are driven by interfaces where actions are initiated by clicking buttons on a ‘control panel’ type view. They are also useful for ‘end of day’ processing that runs after hours.
If a terminal sequence’s ‘Show dialogs’ property is set to Optionally or Never, the changes are saved, just as if the user manually quit and chose to ‘Save changes’ before quitting.
‘Tail recursive’ and ‘terminal’ sequences are mutually exclusive: a sequence can be one or the other, but not both.
The new features of sequences are scriptable as well. The ‘On error’ property accepts any of the ‘sequence error behavior’ types: {continue, return, stop}. See the AppleScript dictionary for more information.
In Helix 4.x and earlier, errors in conditional sequences would terminate that iteration of the conditional sequence, but allow subsequent iterations to execute, and then continue on with the rest of the sequence chain. If that conditional sequence was to run multiple loops, it would continue with the next iteration. For example, if a conditional sequence set to run 100 times encountered an error in the first iteration, the user would have to endure 99 additional errors, or make 99 attempts to stop the sequence to escape.
Helix 5.0 changed that behavior so that that an error would completely stop the conditional sequence, all subsequent conditional sequences, and subsequent steps in the top level sequence from executing. This ‘overreaction’ was done in an effort to handle a user-initiated stop, i.e: pressing Command-period or clicking a Cancel button in a dialog. The unfortunate side-effect of this change was that it broke some very clever programming techniques that relied on being able to continue after an expected error was encountered.
In Helix 5.3 added the ability to differentiate between a user-initiated stop and an execution error. This allowed conditional sequences to continue (with the next sequence in the chain) when an execution error occurred, yet allowed a user-initiated stop to halt the sequence(s) altogether. Unfortunately, there were now three distinct methods of handling errors, and designers had different preferences. A resource was added that gave the designer the ability to choose between the three options, but the setting was global: it applied to every sequence in the collection.
Helix 7.0’s new On error property gives the collection designer the ability to designate a specific error response for each sequence.
Helix 5.3 through 6.1 use a resource (HCSB) to allow a collection designer control over which error behavior a collection should use.
Helix 6.2 replaces the HCSB resource with the HxSequenceErrorHandling preference.
Both of these methods of controlling sequence errors are now obsolete.