Creating DLL Projects

All in-process simulators are implemented as dynamic linked libraries (DLLs). The following describes the procedures that you need to perform in order to create a DLL project in conjunction with the source files generated by SansGUI.

Creating DLL Projects

We recommend the following naming convention and project location for your new DLL projects:

Project Name: We suggest that you use <Name>_<Major>_<Minor> as the name of your project unless you need to keep all the patch levels and build increments. For example, if you are working on a simulator called MySim in version 1.2, the project name is recommended to be MySim_1_2.
Project Location: We suggest that you create the new project in the working directory where the Schema Definition and other supported files reside.

Suppose you have generated MySim version 1.2.1.8 in the working directory MySim, the contents of the MySim directory will look like:

Directory or File	Description
MySim\	Simulator project directory
MySim.sgs	Schema Definition file
MySim_1_2.sgo	Object Library generated for version 1.2.1.8
MySim_1_2.sgb	Backup of Schema Definition prior to the Object Library version 1.2.1.8 generation
MySim_1_2_1_8\	Source file directory, created by SansGUI Source Code Framework
Base_MyClass.c	Sample source file in C for class Base.MyClass
Base_MyClass.f	Sample source file in Fortran for class Base.MyClass
...	Other source files
MySim_1_2\	Simulator DLL directory
MySim_1_2.dsw	Simulator DLL workspace created by IDE
...	Other simulator DLL project files without source code
Debug\	Debug build directory, will not be used
Release\	Release build directory of the simulator DLL
MySim_1_2.dll	The simulator DLL built for software release
Trace\	Manually created directory for debugging and tracing
MySim_1_2.dll	The simulator DLL built for debugging and tracing

Microsoft Visual C++ IDE

To create a new DLL project in MSVC, do the following:

Run the Microsoft Visual C++ interactive development environment (IDE).
From the File>New dialog, select the Project tab and then select Win32 Dynamic Link Library. Enter a name for your project and select a directory where the project should reside. You can use the above naming convention and project locations. From the example, the Project Name is MySim_1_2 and the Location should be the path of the directory MySim. Click on the OK button to continue to create a new workspace.
From the Win32 Dynamic Link Library dialog, make sure the default An empty DLL project is selected and then click on the Finish button. A confirmation dialog will pop up. Click on the OK button.
Your Visual C++ IDE will be loaded with the new DLL project. Open the Project Settings dialog by using the Project>Settings... menu item. Click on the C/C++ tab. In the Code Generation category, make sure that the Use run-time library: field is set to Multithreaded DLL (using the /MD option) for the Win32 Release mode. You also need to make sure that all the external libraries your project replies upon have been built with this option to avoid any potential conflict with the system's library. All other fields should use the default settings with asterisks (*) appended.
Use Build>Set Active Configuration... to select Win32 Release mode. The reason for doing this is that SansGUI has been built with the Release mode. Your DLL code built with the Debug mode without proper modification may conflict with the run-time library used by SansGUI. We will create an optional Win32 Trace mode in Chapter 6 Testing and Debugging Simulators.
Save the project workspace in the IDE.

Compaq Visual Fortran IDE

To create a new DLL project in CVF, do the following:

Run the Compaq Visual Fortran interactive development environment (IDE).
From the File>New dialog, select the Project tab and then select Fortran Dynamic Link Library. Enter a name for your project and select a directory where the project should reside. You can use the above naming convention and project location. From the example, the Project Name is MySim_1_2 and the Location should be the path of the directory MySim. Click on the OK button to continue to create a new workspace.
From the Fortran Dynamic Link Library dialog, make sure the default An empty DLL application is selected and then click on the Finish button. A confirmation dialog will pop up. Do not worry about the multithread library being disabled at this moment because we will set it later. Click on the OK button.
Important Step: Your Visual Fortran IDE will be loaded with the new DLL project. Open the Project Settings dialog by using the Project>Settings... menu item. In the Settings for: field, select All Configurations. We need to check the following things in the External Procedures category under the Fortran tab: 1) the External Name Interpretations field should be set to As-is because the function names are case-sensitive. 2) all other fields should use default settings with asterisks (*) appended, 3) the Append Underscore to External Names field should be cleared, as default. In addition, change the Category selection to Libraries and then select Threaded in the Reentrancy Support: field and Multithreaded DLL in the Use run-time library: field to avoid any potential conflict with the system's library. Click on the OK button to commit the change.
You can use either the Debug mode or the Release mode to build the project. You also need to make sure that all the external libraries your project replies upon have been built with Multithreaded DLL option consistently. In addition, because the External Name Interpretations option is set to As-is while compiling, the calls to intrinsic and external subroutines, functions, and procedures may need to be in their upper-case form.
Save the project workspace in the IDE.

Inserting Source Files

After the DLL project workspace is created, the next step is to insert the generated source files for the classes in the simulator into the project. To do so, use Project>AddToProject>Files... to locate and select the generated source files. Once you are done, click on the OK button to insert the files.

If you use a single programming language, include all the source files with the associated extension. If you use multiple programming languages in a cooperative IDE, such as MSVC and CVF, you can insert the appropriate source files with the extensions associated with the languages on a class-by-class basis. Normally, we recommend that you implement all the functions in a class in the same language. If you really need to implement the functions of the class in mixed programming languages, you will need to manage multiple source files for that class manually. You also need to incorporate other source files or libraries that your simulator will use in the project workspace.

Building Simulator DLL

Because the SansGUI source code framework generates skeleton code for the class functions, you can immediately build the simulator DLL with all the functions returning SG_R_OK.

Select Build>Build <DLL> or press the F7 key to start building the DLL. The <DLL> in the menu is substituted with your project name with a .dll extension.
The DLL should be built successfully. If the compiler cannot find the SGdll.h (for MSVC) or SGdllf.h (for CVF) include file, you need to add the inc subdirectory in the SansGUI directory in the include file path, as described previously in the Preparing Development Environments section.

$C:\FH_Suite\htmlgifs\home.gif$

SansGUI Modeling and Simulation Environment Version 1.2

http://protodesign-inc.com