![]() |
|
Product | |
Support | |
Everything Else | |
This technote replaces the Sequence Behavior in Helix 6.2 and prior technote. | |
Sequence Behavior in Helix 7.0 | |
Introduction |
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. |
Sequence Types | |
---|---|
Terminology |
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 |
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 |
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 |
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. |
Sequence Chains |
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. |
Sequence Properties | |
Inspector Properties |
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. |
Show Dialogs |
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}.
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. |
Message option |
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}
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. |
Custom message |
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. |
On error |
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}
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. |
On error, open Why? |
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. |
Additional Notes | |
Special Case Sequence Types |
There are also two ‘special case’ sequence types that need to be understood:
|
AppleScript Notes |
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. |
Comments on the History of Sequence Error Handling |
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. |
Obsolete Preferences |
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. |