Bulletin Boards
When an entity in the ACIS model is created, altered, or deleted, a bulletin recording the data structure change is added to a bulletin board. In the modeler's default state (in which logging and auto-check pointing are on), each call to an API function generates a new bulletin board that holds a list of bulletins for recording modifications to the model. The bulletin board holds pointers to the first and last bulletin, and to the next bulletin board (refer to following figure).
Figure. Bulletin Board Structure
The BULLETIN class provides functions that read the status of the current bulletin board: retrieve the first, last, next, and previous bulletin on a particular bulletin board; retrieve the old and new entity pointer from a bulletin board; and retrieve the type of bulletin.
Note: An application can read, but cannot alter, the records in a bulletin.
The ACIS programmer has control over roll back through APIs (api_note_state, api_change_state, api_change_to_state, api_find_named_state, api_name_state, api_roll_n_states, and api_delete_ds) and macros (API_BEGIN, API_END, API_NOP_BEGIN, API_NOP_END, API_TRIAL_BEGIN, and API_TRIAL_END). ACIS is shipped with the default of api_logging TRUE. Therefore, the system automatically logs all operations. This is the primary control of whether the application will support undo/redo. When api_logging is set to FALSE, ACIS discards all but the current delta state.
Bulletin Board APIs
API functions start by calling api_bb_begin and end by calling api_bb_end. The API api_bb_begin turns auto-checkpointing off; api_bb_end turns auto-checkpointing on.
When auto-checkpointing is off, the system adds bulletins to the current bulletin board rather than creating new bulletin boards. Because auto-checkpointing is turned off at the beginning of each API function, nested API functions do not create new bulletin boards.
Auto-checkpointing is an accumulating option. For example, if auto-checkpointing is on, then turned off three times by calls of api_bb_begin, it is not turned on until three calls have been made to api_bb_end.
If an API call fails, the current bulletin board is preserved to make it available for debugging. At the next call to an API function, the model is rolled back to the state before the API call failed.
Bulletin Board Macros
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.
Bulletin Board Compression
If an entity has been modified in several different API_BEGIN / API_END blocks, there will be several bulletins for that entity, each on a different bulletin board.
When the option compress_bb is on (default), at the end of each successful block the bulletins in the bulletin board created for that block are merged with those from the previous bulletin board, so they appear as though the operations occurred in the same block. This should save memory used by extra bulletins and backup copies of modified entities. It should also save time during roll back.
In some cases performance can be improved by setting the compress_bb option off, since the time to compress the bulletin boards can be prohibitive in cases in which a single delta state is used for many API calls.
[Top]
© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.