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. |
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. 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.
The following sections describe how to develop Open C API
applications using Microsoft Visual Studio. 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++
You can start Visual C++ via the icon in the Start menu or by typing
"devenv.exe" or "devenv" from an
NX command prompt window.
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:
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
Configure Project Settings
Add Files To The Project
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.
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.
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 2005will 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.
The following sections describe how to develop Open C API
applications using Microsoft Visual Studio 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.
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.
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.