Reviewed and Revised May 2024
As an alternative to external (server-side or application-level) validation, where XTREE returns from the xcall back to the application, local (client-side) validation is also supported via an internal call from XTREE to a specified SBX resident on the client. The advantage of local validation is an improvement in responsiveness by eliminating the overhead of exiting from the XCALL, passing all of the information back to the application which then has to XCALL XTREE again, passing all the relevant parameters back again. The difference is most noticeable in ATE environments, where the parameters have to be passed across a network connection between the client and server, but it also applies, to a lesser degree, to environments where the application and XTREE are executing on the same machine. A secondary advantage of the local validation method is that by encapsulating the validation / formatting logic in an SBX, it may be possible to share certain validations across many programs.
To enable local validation, you must first specify the name of the SBX via an Advanced Coldef Option:
LocValSBX=name
The option must be applied to the zero column, as only one SBX can be specified for each tree. The SBX name should be specified without any path or extension. The SBX is expected to be found either in the current directory or in the BAS: directory. If not found, no local validation occurs.
To specify local validation for a column, add one of these new cformat codes to the column definition:
Value |
Validation Description |
|---|---|
V |
Conditional validation (if the cell changes during editing) |
v |
Unconditional validation (whether it changes or not) |
Note that these are analogous and parallel to the server-side validation codes X (conditional) and x (unconditional).
Typically you would only want to perform one style of validation per column, i.e. local/client or traditional/server, but it is possible to specify both, in which case the local validation is performed first. This technique could be useful as a transitional/experimental technique. Depending on the information returned from the local validation routine, it can disable the server validation, although you can force the server validation to occur regardless of the local validation result by doubling the X or x code. For example:
Value |
Validation Description |
|---|---|
v |
local unconditional |
xv |
local unconditional, possibly followed by server unconditional |
XXV |
local conditional always followed by server conditional |
The local validation SBX performance advantage comes with a couple of limitations:
•It has visibility to only the current answer row. It cannot see the data array row (assuming answer and data arrays are separate), nor can it see any other row in the answer or data arrays.
•Unlike the traditional/server validation, which runs outside of XTREE and therefore has tremendous latitude as to how, or even whether to return to the tree, the local validation must return to the tree. Its only options are to update the current row, to select which cell on the row to re-enter in, and to force XTREE to exit with a specified exitcode.
History
2022 April, A-Shell 6.5.1715: Add feature to A-Shell
Subtopics
