Home > Getting Started Guide > Architecture > Object Libraries

Library Initialization and Termination

The ACIS initialization and termination requirements support the composite component library structure of the product. The fundamental process includes starting the modeler and initializing all required components before use and to terminate all initialized components and stop the modeler after use. The initialization and termination methods of each component are called by a primary method of the composite library of which they are a part. In other words, a primary initialization and termination function is used for each composite library, and not for each component. The primary initialization and termination methods for each composite library are listed below.

Table. Composite Library Initialization and Termination Functions

Composite Library

Initialization Function

Termination Function

SpaBase

initialize_base()

terminate_base()

SpaACIS

api_initialize_kernel()

api_terminate_kernel()

SpaABlend

api_initialize_blending()

api_terminate_blending()

SpaALops

api_initialize_local_ops()

api_terminate_local_ops()

SpaAPart

api_initialize_part_manager()

api_terminate_part_manager()

SpaASurf

api_initialize_skinning()

api_terminate_skinning()

SpaAWarp

api_initialize_warp()

api_terminate_warp()

SpaAVis

api_initialize_faceter()

api_terminate_faceter()

SpaHBridge

api_initialize_hoops_acis_bridge()

api_terminate_hoops_acis_bridge()

SpaHPart

Not needed

Not needed

SpaPhlV5

Not needed

Not needed

admhusk

api_initialize_deformable_modeling()
api_initialize_admhoops()

api_terminate_deformable_modeling()
api_terminate_admhoops()

Applications must initialize the ACIS modeler and the individual component libraries before use, and terminate them after use.

While every ACIS-based application is different, each application developed in C++ using ACIS will need to follow a similar basic framework. This not only includes initializing and terminating the modeler and components, but also checking the results of API calls which is discussed further in this section.

Topics include:

APIs to Start and Stop the Modeler

Two APIs are provided for starting and stopping the ACIS modeler:

api_start_modeller
The API api_start_modeller starts the modeler, defines some global variables, and does a simple check on whether static initializers have been called (which can be a problem for non-C++ application developers). Its call must precede calls to any other API, DI function, or class method.
api_stop_modeller
The API api_stop_modeller attempts to release all memory allocated by ACIS. The application should not attempt to reference any data returned by earlier calls to APIs or DI functions after calling api_stop_modeller. Its call must not be followed by calls to any other API, DI function, or class method.

Note:  These APIs use the British spelling of the word "modeler" in their names. This spelling uses two "l"s: modeller.

Component Libraries

The libraries for each ACIS component must be initialized before use and terminated after use. When an ACIS component is initialized, it initializes any components upon which it depends, so an application only needs to initialize the highest level components in the flow of dependency that it uses. It is the developer's responsibility to make sure any component is initialized by the application before use.

Any component library that was initialized must be terminated. Libraries should be terminated in the reverse order from which they were initialized, to avoid memory problems.

Refer to Object Libraries, for information about the functions for component library initialization and termination. Refer to the Getting Started Guide Home Page for a component dependency diagram.

Other Functions

Some ACIS components may require calls to additional initialization or termination functions. For example, api_rh_initialise_image_utilities initializes the rendering base Image Format Utilities Library. Refer to the function lists in online help for information on initialization and termination functions.

Checking API Results

Each API function returns a result as an outcome object, which indicates the success or failure of the API. The result of every API call should be checked by an application (using outcome methods), followed by appropriate error handling.

Refer to the outcome class reference template in online help for more information.

Global Variables

A global variable is a variable which has unrestricted scope. ACIS has global variables that the customer should know about and possibly use. The following list of ACIS globals may be used and some may even be modified. Before modifying the non-const globals, be sure you have an understanding of the possible impact.

NULL_REF

NULL_REF is a C++ reference to a NULL pointer. Within ACIS, it is a not just a value (like NULL), but a global constant. It is defined as:

void * const NULL_REF=NULL;

When using ACIS APIs, you may find that you need to use NULL_REF. For example, if you wanted to call api_copy_entity_contents with an AcisOptions parameter but without specifying the optional transform, you might call it like this:

api_copy_entity_contents(ent, copy, *(SPAtransf *)NULL_REF, acis_opts);

null_unitvec, null_vector

These globals are zero-length representations of SPAunit_vector and SPAvector respectively.

x_axis, y_axis, z_axis

These globals are zero-length representations of SPAunit_vector and SPAvector, respectively.

Application Layout

The most simple ACIS-based C++ application can be broken down into three sections:

Setup and initialization
Include appropriate header files, start the modeler, and initialize components.
Modeling
Perform all modeling (and other application) functionality.
Cleanup and termination
Clean up any remaining memory allocations, terminate components that were initiated, stop the modeler, and terminate the program.

Refer to the pseudo code in the following figure. This general application layout also applies to more complex applications, but the central "modeling" section would include such things as the provision of an appropriate user interface (for example, windowing, and graphical input/output), file management, model management, application data manipulation, and memory management.

Figure. C++ Application Layout

Simple C++ Application Example

The code snippet in the following example illustrates the basic framework of a very simple ACIS-based C++ application. It starts and stops the modeler, initializes and terminates libraries, and checks the results of API calls, for example. This example uses a simple macro for API result checking and error reporting. Complex applications may need sophisticated error handling.

The header files (or paths) and/or the API arguments may not be those for the current release.

C++ Example

// Include header files
#include < stdio.h >
#include "acis.hxx"
#include "api.hxx"
#include "kernapi.hxx"
#include "cstrapi.hxx"
#include "body.hxx"
#include "position.hxx"
#include "entity.hxx"
// Create a simple macro for checking the results of an API call
// (using outcome class); this macro inserts the required semicolon
// following function call
#define CK_OK(API_FUNCTION) \
{ \
	outcome oc = API_FUNCTION;\
	if (!oc.ok())\
	{\
		err_mess_type errNum = oc.error_number();\
		fprintf(stderr, "%s (%d): %s (%d)\n",\
		__FILE__, __LINE__,\
		find_err_mess(errNum), errNum);\
	} /* end if */\
}

void main ()
{
	// Start the modeler and initialize component libraries
	CK_OK(api_start_modeller(0))// memory size as needed
	CK_OK(api_initialize_constructors())
}

Example. Simple Application Example

[Top]

© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.