|
Macros
API_TRIAL_BEGIN and
API_TRIAL_END can be used to bracket code that may or may not have results you want to keep. Like
API_NOP_BEGIN,
API_TRIAL_BEGIN creates a stacked bulletin board. In
API_TRIAL_END, the outcome result is checked. If the result is good, the model edits are retained and the stacked bulletin board is merged with the main bulletin board. If the outcome is bad, the results are rolled away as if
API_NOP_BEGIN and
API_NOP_END had been used. These "trial" macros only work if logging is turned on. Therefore, bulletin board logging is temporarily turned on in
API_TRIAL_BEGIN and reset in
API_TRIAL_END.
|
|
|
API_TRIAL_BEGIN creates a stacked bulletin board. The stacked bulletin board is logically nested inside an already existing bulletin board, if one exists. Nesting of the associated macros must be strictly maintained.
|
|
|
The main difference between these "trial" macros and the "normal"
API_BEGIN/API_END macros is in the timing and in what gets rolled back. The trial macros create a stacked bulletin board so the rolling section is exactly what is between the two macros, regardless of how they may be nested inside other sets of macros. In the trial case, the roll back occurs in
API_TRIAL_END, whereas in the normal case, the roll back is delayed until the next bulletin board is opened. In the normal case, the roll back is also dependent on the error eventually getting propagated to the outermost
API_END. The trial case always rolls back on failure without having to propagate to the outermost level.
|