The calls to
api_pm_start_state and
api_pm_note_state (or
api_part_start_state and
api_part_note_state) must be strictly paired regardless of errors. Start state and note state are paired by the use of a static level counter. If the note state were skipped when there was an error, the counter would be off by one and subsequent states would not be noted.
|
|
int depth;
|
api_pm_start_state(depth);
|
API_BEGIN
|
|
result = api_do_stuff_1(args);
|
check_outcome(result);
|
|
// If result is not ok,
|
|
|
|
|
|
|
|
// jump to API_END
|
|
// Alternate style of using check_outcome
|
check_outcome(api_do_stuff_2(args));
|
|
// Tell the part manager and graphics what happened
|
record_entity(new top level entity);
|
update_entity(modified top level entity);
|
|
API_END
|
api_pm_note_state(outcome(API_SUCCESS), depth);
|
|
If an error occurs, it will be caught by
API_END. The
api_pm_note_state is always called regardless of error. Note that the outcome is checked before recording or updating entities, so the part manager and graphics don't see anything bad. The check level is controlled by the option
history_checks.
|
|
You can also use
API_SYS_BEGIN/END or
EXCEPTION_BEGIN/TRY/CATCH/END with
api_pm_start_state in the
EXCEPTION_BEGIN block and
api_pm_note_state in an
EXCEPTION_CATCH( TRUE ) block.
|