xcall <NAME>, op, treeid, ansrow, cpos, clen, xtrctl, status, exitcode
Parameters
op (Num) [in]
Indicates operation/request from XTREE. 1 indicates the first version (as documented below). Subroutine should respond to anything other than recognized op values by setting status to XVF_BAD_OP.
treeid$ (String) [in]
Tree identifier as set by the Advanced Column Option TreeID clause.
ansrow (X) [in/out]
The current row of the answer array, i.e. the one corresponding to xtr.XROW
cpos (Num) [in]
Starting position in ansrow of exit column (i.e. xtr.XCOL)
clen (Num) [in]
Length of the column specified by xtr.XCOL
xtr (XTRCTL) [in/out]
On input, this is a copy of the XTRCTL as it would be returned to the traditional/server validation. On return, the xtr.TARGETCOL should specify the re-entry column. See Identifying Exit Column below.
status (Signed Num) [in/out]
Indicates status of validation operation. On input it will be set to XVF_INCOMPATIBLE, under the theory that any compatible validation SBX will change it to one of the other status values on return:
Symbol |
Value |
Meaning |
|---|---|---|
XVF_NOP |
9000 |
Incompatible validation module |
XVF_BAD_OP |
9001 |
Unsupported op - indicates this SBX doesn't support the op value passed. (SBX is out of date, new XTREE version?) |
XVF_ERROR |
9002 |
Internal error occurred in the SBX |
XVF_NV |
9003 |
Field Not Valid (fails validation criteria). SBX would normally also set xtr.TARGETCOL to xtr.XROW to re-enter at same cell. Any changes to ansrow made here will be updated back to the XTREE. Exitcode should be set to 0 unless you want to force an app-level validation exit. |
XVF_OK |
9004 |
Field Valid; no update to row data required. Exitcode should be set to 0 to prevent a redundant app-level validation exit. (App can still override that in coldef - see below) |
XVF_OK_UPD |
9005 |
Field Valid; ansrow has been modified (so XTREE needs to re-load the cells on this row). Exitcode should be set to 0 to prevent a redundant app-level validation exit. (App can still override that in coldef - see below) |
Note XTREE updates the tree contents based on changes made here to the ansrow ONLY when the return status is XVF_NV or XVF_OK_UPD. In all cases, unless exitcode # 0, XTREE will re-enter at the cell determined by XTR.TARGETCOL.
Beyond that, the status value is mainly for debugging purposes. See Debugging below.
The main return values of significance to XTREE are xtr.TARGETCOL (where to re-enter), exitcode (whether to exit to app), ansrow (containing and updates to cells on the row), and any message boxes displayed to tell the user about validation problems.
exitcode (Signed Num) [in/out]
On input, contains the exitcode value that XTREE will send back to the application if no action taken here. -48 indicates column tagged for normal app-level validation; if the value is not reset here, it will cause XTREE to exit with the specified exitcode following the local validation. On output, set to 0 to re-enter the tree directly, or any other exitcode to pass back to the app.
valver (Num) [out]
Returns the edit # of this module. This is purely for debugging purposes, which see below.
