|
There are three sets of macros for
BULLETIN_BOARD creation, which differ in how they handle error conditions and stacked bulletin boards.
|
|
|
API_BEGIN /
API_END are the basic macros used to wrap all modifications to the model. The auto-checkpointing counter is incremented in
API_BEGIN and decremented in
API_END. Be careful not to jump out of an
API_BEGIN /
API_END block using
return
or
goto, because it gets the counter out of synchronization. Model changes not wrapped in these macros cause a
sys_error(NO_CUR_BB) to be issued.
|
|
|
API_BEGIN opens a new bulletin board without any bulletins. However,
API_END does not close that bulletin board. The bulletin board is not closed until the next
API_BEGIN. This delay in closing the bulletin board is to handle error conditions that might have occurred while changing the model. A bulletin board is also closed after a note state operation (api_note_state). The option
bb_immediate_close can be used find errors that result when a delta state and bulletin boards are logically closed.
|
|
|
For history and roll to function properly, functions that change the model must be enclosed within the two macros,
API_BEGIN and
API_END. To create one bulletin board for multiple API calls, nest them within these macros. In such nested cases, new bulletin boards are not created; instead, entity changes are attached to the bulletins within the current bulletin board. When using
ACIS APIs to create modeling elements, each API generally opens a new bulletin board because it has
API_BEGIN and
API_END as part of its code.
|
|
|
If an error occurs, control jumps to the
API_END. If an error occurs in a nested
API_BEGIN /
API_END block, control jumps to the
API_END and proceeds from there. If the
API_END was at the outermost level of nesting, the counter goes to zero and the
BULLETIN_BOARD is marked as failed, then closed. The model will be invalid.
|
|
|
At this point one may look at the
BULLETIN_BOARD and the (now invalid) model for feedback about the error. When the next
BULLETIN_BOARD is opened, the changes in the failed
BULLETIN_BOARD will be rolled back and discarded. It is up to the programmer to check the result and resignal the error (using
sys_error), to avoid problems with an invalid model in later operations. If the error is not resignaled to the outermost
API_END, the
BULLETIN_BOARD will not be marked as failed and the changes will not be rolled back.
|
|
|
API_NOP_BEGIN /
API_NOP_END are used for operations that change the model, but where the user does not want the model changed or any
BULLETINs to be created. Typically they are used in query operations, including ray testing and evaluation that may add boxes to the model but make no user perceptible change.
|
|
|
API_NOP_BEGIN causes a new
BULLETIN_BOARD to be created and stacked, regardless of the nesting level counter.
API_NOP_END rolls back and discards the changes in the stacked
BULLETIN_BOARD.
|
|
|
API_TRIAL_BEGIN /
API_TRIAL_END can be used to test operations that may or may not work. For example, a user interface may allow a user to preview creation of segments of a sketch, but have the option to abort them. By wrapping the changes in
API_TRIAL_BEGIN /
API_TRIAL_END, one can cause the abort to occur by setting an error code in the outcome, or keep the changes by not setting an error. These macros are also useful for optimization. One may first try a quick algorithm that does not always work and roll it back and use a more robust but slower algorithm if it fails. Simply wrap the quick algorithm in
API_TRIAL_BEGIN /
API_TRIAL_END and check the outcome.
|
|
|
API_TRIAL_BEGIN stacks a new
BULLETIN_BOARD, just as
API_NOP_BEGIN does. In
API_TRIAL_END, the result is checked. If the operation was successful, the resulting bulletins are merged with the
BULLETIN_BOARD it is stacked on top of. If the operation failed, the changes are rolled back and discarded.
|