Outcome Checking, Logging and Progress Reporting in 3D ACIS

This article shares a simple architecture which can be used to capture meta-data about the use of ACIS APIs in your program. It can be used to record the filename, line number, arguments and outcome of each API. C language preprocessor macros are used to invoke methods on a static object called spa::CheckOutcome. The meta-data is sent to your implementation of spa::CheckOutcome::Logger interface.

Here is an example of the output produced by a simple implementation of the Logger interface:

api_start_modeller(0) from main.cpp @ line 56: OK
api_initialize_kernel() from main.cpp @ line 58: OK
api_set_file_info(0x01 | 0x02, fi) from main.cpp @ line 64: OK
api_solid_block(SPAposition(), SPAposition(), block) from main.cpp @ line 70: ERROR (width negative or zero)
api_solid_block(SPAposition(), SPAposition(1,1,1), block) from main.cpp @ line 73: OK
api_save_entity_list(fptr, true, elist) from main.cpp @ line 78: OK
api_restore_entity_list(fptr, true, elist) from main.cpp @ line 83: OK WARNING (restore data has unknown origin)
api_terminate_kernel() from main.cpp @ line 87: OK
api_stop_modeller() from main.cpp @ line 88: OK

Additionally, the spa::CheckOutcome class contains an interface that can be implemented to report and interrupt the progress of the API. The interface also provides pre-API and post-API methods that are invoked accordingly, which allow you to more easily show and hide a progress dialog box. Here is an (abbreviated) example of the output produced by a simple implementation of the Progress interface:

Restoring entity list (0%)
Restoring entity list (1%)
Restoring entity list (3%)
Restoring entity list (5%)
Restoring entity list (7%)
…
Restoring entity list (100%)
API call completed. result == ok

Using this architecture in your code is quite easy. Just surround each of your API calls with the checkOutcome or checkOutcomeWithProgress macros. Here are two examples of its use:

if(!checkOutcome(api_initialize_kernel())) {
std::cout << "Initialization failed: "
<< spa::CheckOutcome::getLastErrorMessage()
<< std::endl;
return -1;
}

if(!checkOutcomeWithProgress(api_restore_entity_list(fptr, true, elist), "Restoring entity list")) {
std::cout << "Restore failed: "
<< spa::CheckOutcome::getLastErrorMessage()
<< std::endl;
}

As you can see from these samples, spa::CheckOutcome provides you with easy access to the error message in the event of a failure. Additionally, the success or failure of an API call is simplified to a Boolean value by the checkOutcome macro which can be used more naturally in conditionals.

It is important to check the return value of your ACIS API calls and respond to failures appropriately. Information about the success of an API is returned in an outcome object. When an API fails, the outcome object can be queried to obtain specific information about the failure. The static method spa::CheckOutcome::getLastOutcome() can be used to obtain last outcome object for further processing when needed.

All of the capabilities described are can be easily added to your application. Just add click here to download CheckOutcome.cpp and CheckOutcome.h , then add the files to your project. To see an example implementation of the Logger and Progress interfaces, as well as how spa::CheckOutcome and the macros are used take a look at main.cpp.