Tutorial:ACIS Tutorial 2a: Creating an ACIS Application Using Visual Studio

From DocR23

This tutorial describes how to build a very minimal ACIS application using Microsoft's Visual Studio.

Create a "hello world" Application in Visual Studio

You should already be familiar with programming in your development environment; however, to illustrate the changes that must be made to create an ACIS application we will present a simple application first without ACIS linked into it and then again with ACIS linked into it. These instructions have been created using Microsoft Visual Studio 2005, version 8.0, but are generic so should apply to other versions as well. For the first non-ACIS application we shall use the following source file.

#include <stdio.h>
 
int main (int argc, char** argv) {
	printf ("Hello, World!\n");
	return 0;
}

1. Start Visual Studio.

   One method is to open a new command window; execute vsvars32.bat; and then execute devenv.

2. Create a new Project.
   1. Select File-New-Project.
   2. Set the Project Type to be Visual C++ Win32 and Console Application.
   3. Give it a unique name.
   4. This will bring up a Wizard.
   5. Select the Additional Option of Empty Project.
3. Create a new file to contain the main program using File-New-File. After creating the source file:
   1. Save the source file.
   2. Add the existing file to the project.
4. Build (that is, compile) the source file. Modify the source file and rebuild until no compilation errors exist.
5. Execute the program by Debug-Start Without Debugging.
6. Save everything using File-Save All.
7. Quit using File-Exit.

This procedure should be very familiar if you are familiar with programming in Microsoft's Visual Studio.

Create a Minimal ACIS Application

The primary changes needed to create an ACIS application are:

1. We need to define two environment variables, A3DT and ARCH, which are used during pre-compiling and linking.
2. We need to modify the definition of the PATH variable.
3. We need to include ACIS header files.
4. We need to call an application-specific ACIS licensing function. (University customers also need to register each installation of ACIS-based products. Refer to Registration.)
5. We need to start the modeler and initialize the necessary components.
6. We need to terminate all initialized components and stop the modeler.

#include <stdio.h>
#include "acis.hxx"
#include "kernapi.hxx"
 
// Declaration of the licensing function
void unlock_spatial_products_<NNN>();
 
// The main program...
int main (int argc, char** argv) {
 
	// Start ACIS.
	api_start_modeller(0);
 
	// Call the licensing function to unlock ACIS.
	// This can be done right after calling api_start_modeller().
	unlock_spatial_products_<NNN> ();
 
	// Initialize all necessary add-on components (none in this example). 
 
	// Your application code goes here.
	printf ("Hello, World!\n");
 
	// Terminate all necessary add-on components (none in this example). 
 
	// Stop ACIS and release any allocated memory.
	api_stop_modeller();
 
	return 0;
}

A procedure to create an ACIS application using Visual Studio is given below.

1. Obtain a license file from Spatial's Downloads Center or contact Spatial’s Customer Support. Additional information on ACIS licensing is available at Application Licensing.
2. Open a new command window; set A3DT and ARCH; and then modify PATH.
   1. A3DT is the path to the ACIS libraries.
   2. ARCH is the architecture or platform (for example, NT_VC8_DLLD.)
   3. Prepend %A3DT%\bin\%ARCH% to the existing PATH.
3. Execute vsvars32.bat and devenv as before.
4. Create a new project as before.
5. Select Project-Properties.
   1. Under C/C++ General, Additional Include Directories add $(A3DT)\include.
   2. Under C/C++ Preprocessor, Preprocessor Definitions add $(ARCH).
   3. Under Linker General, Additional Library Directories add $(A3DT)\lib\$(ARCH).
   4. There are several more directives listed in the on-line Installation documentation, but these should be sufficient for our minimal ACIS application.
6. Create a new source file.
7. Add the ACIS license file to the project directory and to the project. (This file includes example code for error handling that can be modified or commented out.)
8. Build, Execute, Save, Exit as before.

Discussion Regarding the Minimal ACIS Application

It is tempting to immediately start adding to this minimal application, but before we start doing that let's briefly look at this application.

The first ACIS related header file is acis.hxx. This header file should be included in all files that contain ACIS code. Moreover, it should precede all other ACIS header files and all application header files. It may come after system header files.

The only other ACIS header file that has been included is kernapi.hxx. This header contains declarations for a many of the most commonly used API functions in the ACIS kernel component.

The first ACIS related function call is api_start_modeller. api_start_modeller must be called before calling any other ACIS functions, with the exception of initialize_base. (Calling initialize_base is optional. It allows one to control the use of the free list and memory leak tracking subsystem. It even allows one to completely replace the ACIS memory management system. Whenever initialize_base is called before api_start_modeller, terminate_base should be called after api_stop_modeller. For more information on initialize_base, refer to base_configuration or Memory Management.) api_start_modeller should be called only once in an application.

We must call the ACIS licensing function after we have initialized the memory management system (which happened during our call to api_start_modeller.) If this is not done, ACIS functionality will not work.

In ACIS versions prior to R20, each ACIS component needed to be initialized separately (such as Blending and Local Ops). While these component initialization functions still exist and can be called, beginning in ACIS R20, all core ACIS components are initialized upon calling api_start_modeller. Correspondingly, api_stop_modeller handles the termination of all core ACIS components. Note that if your application still continues to make separate calls to the component initialization functions, your application must also have matching calls to the respective component termination functions.

However, non-core ACIS components must still be initialized individually, for example, PHL V5 and Defeaturing. For a description of which components are in which ACIS libraries, refer to ACIS Libraries and Library Initialization and Termination.

At this point ACIS is up and running. Congratulations!

After printing our "Hello, World!" message, we must properly shut down ACIS. This is done by terminating all the non-core components we initialized (none), and then calling api_stop_modeller. No ACIS function calls should come after api_stop_modeller. The only exception to this is terminate_base, which should only be called if you called initialize_base before api_start_modeller.

Enhance and Restructure the Minimal ACIS Application

In Tutorial 1, we mentioned that ACIS API functions return information regarding the success or failure of the API function. In the first implementation of our minimal application we ignored the objects returned by the API function calls. Let's modify our application to check the results of our API function calls. At the same time let's restructure the code to make subsequent tutorials easier to understand. Below is a revised source file for the minimal ACIS application. You should be able to simply replace the first version of the file with the revised version and rebuild your application.

#include <stdio.h>
#include "acis.hxx"
#include "api.hxx"
#include "kernapi.hxx"
 
// Declaration of the ACIS licensing function.
void unlock_spatial_products_<NNN>();
 
// Declaration of our functions.
void do_something();
int my_initialization();
int my_termination();
 
// The main program...
int main (int argc, char** argv) {
 
	int ret_val = my_initialization();
	if (ret_val) 
		return 1;
 
	do_something();
 
	ret_val = my_termination();
	if (ret_val)
		return 1;
 
	return 0;
}
 
void do_something(){
	// Your application code goes here.
	printf ("Hello, World!\n");
}
 
int my_initialization() {
 
	// Start ACIS.
	outcome result = api_start_modeller(0);
	if (!result.ok()) {
		err_mess_type err_no = result.error_number();
		printf ("ERROR in api_start_modeller() %d: %s\n",
			err_no, find_err_mess (err_no));
		return err_no;
	}
 
	// Call the licensing function to unlock ACIS.
	unlock_spatial_products_<NNN>();
 
	// Initialize all necessary add-on components (none in this example). 
 
	return 0;
}
 
int my_termination() {
 
	// Terminate all necessary add-on components (none in this example). 
 
	// Stop ACIS and release any allocated memory.
	outcome result = api_stop_modeller();
	if (!result.ok()) {
		err_mess_type err_no = result.error_number();
		printf ("ERROR in api_stop_modeller() %d: %s\n",
			err_no, find_err_mess (err_no));
		return err_no;
	}
 
	return 0;
}

In the latest version of our program, we examine the outcome returned by each API function call. An outcome contains an error number, among other things. In the event of an error (which should never occur with this simple program!), we print out the error number and its associated error message. Because of the seriousness of an error during start up or shut down, we quickly exit the application if an error occurs. Usually you will not exit your application when API functions produce errors. You may have noticed that my_initialization and my_termination are of type int, yet they return an err_mess_type. An err_mess_type is a typedef'd int. Handling exceptions is discussed in more detail in Tutorials (Exception Handling).