Windows Operating System Setup

This section begins the machine specific information for setting up Open C API on a Windows Operating System and includes the necessary information you need to create environment variables, compile, link, and run your Open C API programs.
 
NOTE: NX does not support the use of FORTRAN in Open C API programs in the Windows Operating System environment.
 
This section describes the variable you need to define for Open C API. We list the variable and its description in the following table.
 
Variable Description
UGII_USERFCN  This variable points to the directory where the Open C API libraries reside. You can define this variable by executing the script %UGII_BASE_DIR%\ugopen\ufvars.bat.
CL This system environment variable is used to pass default options to the MSVC++ compiler. The ufvars.bat script initialized this variable with options needed for Open C API compiles.
INCLUDE This system environment variable is used to enable the C preprocessor to locate headers (.h files). The ufvars.bat script modifies this variable to incorporate the location of the Open C API headers.
LIB This system environment variable is used to enable the linker to locate object libraries and import libraries. The ufvars.bat script modifies this variable to incorporate the location of the Open C API import libraries, libufun.lib and libugopenint.lib.
PATH This system environment variable is used to enable the system to locate executables, DLL's and scripts. The ufvars.bat script modifies this variable to enable easy access to the uflink.bat script.

 

Open C API Modes, Functions, and User Exits

The following paragraphs provide descriptions of these items with respect to the Windows Operating System.
 
External Open C API programs are executable images (.exe) that run and can access the NX database without bringing up interactive NX. These are programs which make reference to Open C API entry points in the dynamic link library libufun.dll. This dll must be accessible at run-time. Normally NX dlls are found in a directory in the user's %PATH% variable, which is configured by the NX installation. An external Open C API program is linked with an import library, libufun.lib, which specifies all of the available entry points in libufun.dll. This import library is located in the %UGII_BASE_DIR%\ugopen directory and is not required at run-time.
 
Internal Open C API programs are implemented as dlls which themselves are loaded by NX at runtime. It is necessary for the Internal Open C API programs to include uf.h to obtain the function prototype for ufusr in order that it be properly exported from the user's dll. Otherwise your program may link but will not run due to the missing entry point.
 
User Exits are programs that are also implemented as dlls which are loaded by NX at runtime. As on Unix platforms the location of the user's program is specified by an environment variable which implies when it should be invoked and the name of the entry point to be executed. It is necessary to include uf_exit.h to obtain the function prototypes for the various User Exit functions.
 
The available entry points in libufun.dll and libugopenint.dll are limited to the published interface for External Open C API and Internal Open C API, respectively.
 

Developing From a Microsoft Visual C++ Project

The following sections describe how to develop Open C API applications using Microsoft Visual Studio 2005 (V8.0). It is recommended that all Open C program development on Windows be done from a Visual C++ project.  Also projects should be developed on the same platform that they will be run on (images for a Window 32 bit platform need to be compiled and linked on a 32 bit platform - same for the Window 64 bit platforms).
 
Starting Visual C++
 
To ensure proper set up of NX environment variables, we recommend you always start the Visual Studio from an NX Command Prompt window using the command "devenv" rather than by using the icon in the Start menu.
 
Creating a Visual C++ Project
 
You have two choices for creating a Visual C++ project. You can create a project by using the Open C AppWizard, or by creating a project manually. It is highly recommended that you choose the Open C AppWizard. It automatically performs all of the steps described in "Creating an Open C Project Manually".  Images that will be run on the Windows 32 bit platform must be built on a 32 bit platform.  Images that will be run o the Windows 64 bit platform must be built on a 64 bit platform.
 
Using the Open C AppWizard
 
To use the Open C AppWizard:
  1. Select the File-->New menu item to activate the New dialog and click the Projects tab.
  2. Select Open C AppWizard from the list of project types.
  3. Enter a project name into the "Project name:" text box. By default this becomes the name portion of the program being built. For instance, a project named "MyNXOpenApp" produces either a "MyNXOpenApp.dll" or "MyNXOpenApp.exe". You can override this later if necessary.   Note: On the Windows 32 bit platform the Release Configuration will be set to Win32.  On the Windows 64 bit platform the Release Configuration will be set to x64.
  4. Click "OK" and follow the on-screen instructions to create your Open C project.

 
Creating an Open C Project Manually
 
To create an Open C Project manually, you must: create a new project, configure project settings, and add files to the project. The details follow.
 
Create a New Project
  1. Select one of the following project types:
    "Win32 Dynamic-Link Library" for an internal Open C application
    "Win32 Console Application" for an external Open C application.
  2. Configure other options if desired.
  3. Press the "OK" button to create the project.

 
Configure Project Settings
  1. Configure compile options.
    Select the "Project->Settings" menu item to activate the "Project Settings" dialog and click the "C/C++" tab.
    In the "Category:" list box, select "Code Generation". In the "Use run-time library:" list box, select "Multithreaded DLL".
  2. Configure link options.
    Click the "Link" tab on the "Project Settings" dialog. In the "Object/library modules:" text box, add the necessary NX libraries. For an Internal mode application, add libufun.lib and libugopenint.lib. For an External mode application add libufun.lib. When linking a C++ image include libopenpp.lib, libvmathpp.lib, libopenintpp.lib, libnxopenuicpp.lib and libnxopencpp.lib.
    Add the libraries identified in the previous step to the "Object/library modules:" text box.
    Click the "OK" button.
  3. Configure the include path.
    Select the "Tools->Options" menu item to activate the "Options" dialog and click the "Directories" tab.
    In the "Show directories for:" list box, select "Include files". Add an entry for "%UGII_ROOT_DIR%\ugopen" to the directory list using the proper expansion for the "UGII_ROOT_DIR" environment variable (e.g. C:\ugnx50\ugopen).
    Use the arrow icon buttons to move the ugopen directory above all other directories.
  4. Configure the library path.
    Select "Library files" in the "Show directories for:" list box of the "Options" dialog.
    Add an entry for "%UGII_ROOT_DIR%\ugopen" to the directory list using the proper expansion for the "UGII_ROOT_DIR" environment variable (e.g. C:\ugnx50\ugopen).
    Use the arrow icon buttons to move the ugopen directory above all other directories.
  5. Click the "OK" button.

 
Add Files To The Project
  1. Select the "Project->Add To Project->Files" menu item to activate the "Insert Files into Project" dialog.
  2. Select the files to be added and click the "OK" button.

 
Check the Release Configuration:
 
Projects are created with a Release Configuration of Win32.  This is correct for building on the 32 bit Windows platform.  If you are on a 64 bit platform, the Release Configuration needs to be changed to x64.  In the Confiugration Manager select "New" and in the New Solutions Platform select a new platform of x64.
 
Compiling and Linking
 
Select the "build" icon or press the "F7" function key to build the project. Projects created using the Open C AppWizard compile and run "as-is".
 
Debugging and Running
 
If the project is an internal Open C application (DLL), the following steps must be performed to associate the NX executable with the project. If these steps are not performed, the application cannot be executed or debugged from the Visual C++ environment. These steps do not apply to external Open C applications (EXEs).
 
Step 1 Determine the location of the NX executable ugraf.exe.
 
Go to the Windows "Start" menu and select "Settings->Control Panel". Double-click the "System" icon. Click the "Environment" tab on the resulting "System Properties" dialog. In the "System Variables" list scroll down until you find a variable named "UGII_ROOT_DIR". The value associated with this variable is the directory path to the "ugraf.exe" executable. Select the "UGII_ROOT_DIR" variable. Highlight the complete path in the "Value" field at the bottom of the dialog and copy it to the clipboard.
 
Step 2 Associate the NX executable with your project.
 
From within Visual C++, select the "Project->Settings" menu item and select the "Debug" tab on the resulting "Project Settings" dialog. Notice that the "Executable for debug session:" field is empty. Place the cursor in this field and then type or paste the path determined in the first step, followed by "\ugraf.exe". For example, if the value of "UGII_ROOT_DIR" were "C:\ugnx50\ugii" then you would enter: C:\ugnx50\ugii\ugraf.exe. You may also browse for the executable file by clicking the arrow button to the right of the "Executable for debug session:" field.
 
Step 3 Set the working directory.
 
The "Working directory:" field on the "Project Settings" dialog specifies the directory from which Visual C++ runs NX. A common convention is to use "C:\TEMP" for the working directory.
 
Step 4 Set the NX program arguments (optional)
 
You may set any NX program arguments you require by entering them in the "Program arguments:" field on the "Project Settings" dialog. The syntax is exactly the same as the command-line syntax for starting NX.
 
Step 6 Run the Application
 
Click "OK" in the "Project Settings" dialog and then run or debug the application as you would normally from Visual C++. NX is started each time the project is executed. You are free to place breakpoints in your Open C application just as you would in any other application. It may take a few moments for NX to appear because Visual C++ is searching for debug symbols in the NX DLLs, so be patient.
 

Print statements

Since NX is a native Windows application, there is no console started up automatically. Therefore using a printf to print to stdout will not work. If you want to use printf statements to debug your internal Open C application, you must add the following code to your internal Open C API function:
 
#include <windows.h>
#include <fstream.h>
#include <stdio.h>
...
FILE *fp;
...

/* allocate console window conout$ */
AllocConsole();
/* reopen stdout on conout$ for fprintf and printf */
fp = freopen("conout$", "w", stdout);
 
This will create a console window and attach it to stdout so that printf and fprintf will work.
 

Known issues

When using Open C++, you should not make an MFC extension DLL in debug mode.
 
This is a well known problem with Microsoft compilers. Microsoft uses different libraries for debug and release configurations. NX will use a release .dll, and so Open C++ will allocate memory using the heap in that library. The customer MFC extension DLL in debug mode will use a debug library, and try to free memory using the debug library. The only work around is to either only build a release configuration, or only build as a WIN32 DLL using the Open C AppWizard.
 

Developing from the Command Line

The following sections describe how to develop Open C API applications using Microsoft Visual  Studio 2005 (V8.0) from the command line.
 
Compiling and Linking
 
Open C API programs may be compiled and linked from a console window. From under the console window you may use makefiles or invoke the compiler and linker manually. We describe both environments below:
 
To define the environment variables mentioned above, select and double click the NX Command Prompt icon located under the NX Program Group.
 
Compiling
 
To compile Open C API C programs use the doskey alias ufcomp. This is supported by the CL and INCLUDE environment variables as specified above. To determine available CL options, use the command CL /?. Some useful options include:
 
/Ox maximum optimization
 
/Od disable optimizations (default)
 
/Z7 include debug information
 
/D{name} define macro {name}
 
/MD compile for linking with msvcrt.lib
 
/MDd compile for linking with msvcrt.lib (debug)
 
/I{dir} add {dir} to include file search path
 
Linking
 
To link Open C API C programs use the shell script uflink. If uflink is executed without any options it prints usage information to the command prompt window. uflink.bat is a wrapper script which provides command line options to the underlying makefile, uflink.mak.
 
The usage for uflink.bat is as follows:
 
uflink (TARGET)=(targetname) [optional object or libraries]
 
where TARGET must assume one of the following values (case insensitive):
 
UFDLL=(targetname).dll UFEXE=(targetname).exe UFOBJ=(targetname).obj
 
A dll is an Internal Open C API program. An exe is an External Open C API program.
 
If the environment variable NODEBUG is set then the target is compiled or linked with full optimization. Otherwise, the target is compiled or linked for debug.
 
Using NMAKE within a console window
 
The makefile ufmake.mak provides inference rules for compiling and linking Open C API programs. For easiest use you should create a Makefile which includes ufmake.mak in its first line and which contains targets with an .obj, .exe, or .dll extension. For example:
 
!include <ufmake.mak>
 
ext_uf_example.exe: $*.obj
 
ext_uf_example.obj: $*.c
 
ufsta.dll: $*.obj
 
ufsta.obj: $*.c
 
This presupposes that %UGII_USERFCN% is in your %PATH% variable, as has been discussed before.
 
Debugging
 
From the Command Prompt, enter the command msdev followed by the name of the program (.exe) you wish to debug. If you are debugging an External Open C API program you would enter msdev [path\]{name}.exe, where [path\] is the optional pathname portion of the filespec and {name} is the required name portion of the executable. If you are debugging an internal Open C API program you would enter msdev [path\]ugraf.exe.
 
From the Program Manager, select the MSVC++ icon, and under the menu bar title choose File-->Open, then choose the executable program to debug.
 
See the MSVC++ documentation for details on how to use the MSVC++ Debugger.
 

Running Open C API Programs

Open C API programs can be run from any of four environments:
 
To run an External application, select "Execute" from Visual C++ or type the name of the application at a shell prompt. When executing from the command line, the dynamic link library libufun.dll must be accessible using the normal search rules that the Windows operating system uses to find a DLL. Typically, libufun.dll is found in the directory specified by the UGII_ROOT_DIR environment variable, which should be included in your PATH environment variable.
 
To run an Internal application from Visual C++, follow the "Debugging" setup instructions under "Developing from a Microsoft Visual C++ Project". To run an Internal application from within NX, use the "File->Execute Open C->User Function..." menu, which displays a file selection dialog that allows you to browse for your application. When you have selected a program, NX attempts to load the DLL and call the "ufusr" entry point. If the DLL cannot be loaded or the entry point cannot be called, an error message is displayed.
 

Error Messages

When setting up the execution of an Internal Open C API program, the following error messages can occur:
 
1. "FILE NOT FOUND" (several) ugraf: unresolved references -- ufxxxx ugraf can't continue
 
Possible cause: The program linked as an Internal Open C API program, but which does NOT have the required UFUSR Entry Point.
 
2. "LIBRARY IS MISSING REQUIRED ENTRY POINT" This can occur if an Internal Open C API program or User Exit does not contain the expected entry point, such as ufusr or ufsta. To determine the entry points in a dll, use the dumpbin utility supplied with msvc++. For example:
 
dumpbin -exports myuserxit.dll
 
Possible cause: If the proper header files (e.g. uf.h for ufusr or uf_exit.h for User Exits) are not used, then the compiler can not see the dllexport attribute of the function prototype and does not know that the function is to be exported from the dll.