Open C API is designed to enable an easy interface between NX and the outside
world. The Open C API consists of:
Open C API programs can run in 2 different environments, depending on how the
program was linked. The two environments are:
Most Open C API functions/subroutines can be used in either mode. There are
only a few, mostly User Interface routines that are only supported in internal
mode.
The Open C API product is not intended to replace the Open C GRIP (GRaphics Interactive Programming)
product, but rather to make it easier to interface to NX from a high-level
language such as C or C++. There are many tasks where a high-level language
program is more appropriate.
The Open C API product is explicitly defined in this manual. It is our intent
to insulate the application programmer from changes in future NX software
releases. Unfortunately, this is not always possible. Where this is not
possible, every effort will be made to support existing routines for at least
one release version of NX prior to obsolescence, and forewarn users of routines
which will be changed in the future.
When upgrading to a new release, programmers are expected to recompile and relink their programs. In addition, the release notes
supplied with each release of NX describe changes that are important to Open C
programmers.
The release notes also describe what versions of the operating system and
compiler were used to create the release of Open C API. Since operating
systems, linkers, compilers, run-time libraries, etc., are usually updated by
the hardware vendors more frequently than NX is released, there may be
combinations that do not function correctly with Open C API. Additionally,
compiling or linking may require different options other than those documented
here. Refer to the Release Notes supplied with each release of NX for specific
changes that may be necessary to use Open C API correctly.
Many of the routines that have example programs
have the C source code files located in the ugopen
directory, which is a subdirectory of the directory pointed to by the variable
UGII_ROOT_DIR. The source code files have a "ufd" prefix followed by a module name and a
descriptive name. For example, ufd_curve_ask_spline_thru_pts.c
is an example source code program that demonstrates the UF_CURVE_ask_spline_thru_pts
function. The source code found in the ugopen
directory should always be preferred over the example code documented in the
Open C API Reference manual due to the possibility of any late changes to
routines that may occur.
Open C API programs can be written in the C or
C++ programming languages.
All Open C API programs must be correctly
initialized and terminated. You use the two C functions UF_initialize and UF_terminate to do this. After you have
declared your variables the first Open C API function call must be UF_initialize. Your last function call must be UF_terminate. In external mode, you may only call UF_initialize once. Once UF_terminate
is called, there is no way to reconnect to the Open C environment. If you
are using the Pre-NX4 Open C API license, UF_initialize
and UF_terminate will allocate and deallocate the Open C API license. If you are using
the new NX4 licensing scheme, the Open C API license is not required, but each
function will require a specific module license. For example, if you call
UF_ASSEM_add_part_to_assembly you must have an
Assemblies license. To view a current table of user functions and their
associated licenses click here license_table.csv
There is a tool available to scan existing user
function programs to determine which module specific licenses will be necessary
to run the program with the new licensing system. Click here query_licenses to download this tool. Note
that Perl is required to execute this tool from the command prompt. You
can download the latest version of Perl from www.perl.com. Once you have Perl installed open a
command prompt and navigate to the directory where you saved the query license
tool. Type 'perl
query_licenses.pl -h' to get started.
To create geometry, cycle a model, or perform
other elementary operations, you must first load an NX part file. Where
routines operate on a particular type of tag, it is imperative that you pass
the correct type of tag to the routine. For example, if you want to query the
coordinates of a point, you must pass in a tag for a point - not the tag for a
line or any other type of geometry. The above are error conditions in almost
all routines. These error conditions are not repeated for each individual
routine.
Many Internal Open C API programs use the
function ufusr as
an entry point. The ufusr function acts as a
main function.
Internal Open C API programs can be thought of as a user written function to NX.
To start execution of the program, NX loads the program into memory and then
references the symbol ufusr. The user's program takes
over execution at that point. At the end of execution, the program executes a
return statement which returns control to NX. The Open C API Programmer's
Guide describes how to build both internal and external programs and
describes example files that are supplied in the Open C kit. See the
"Basic Part File Query" chapter of the Open C API Programmer's
Guide.
The entry point into an Internal program is through a
function/subroutine called ufusr.
/** internal C Open C API program** input* param - parameters passed into the Open C API program from* NX (Reserved for future enhancements)* parm_len - Length of param after implemented (may* not be needed on all platforms, see the* "Writing Open C API Programs" section)** output* retcod - User return code (future enhancement)*/ #include <uf.h>/* Additional include files as required */ void ufusr(char *param, int *retcod, int parm_len)
{ /* statement declarations */ UF_initialize(); /* body */ UF_terminate();}
Once an executable is loaded into memory, it stays resident in memory with the
NX session unless you use methods to unload the image (e.g. see the function ufusr_ask_unload
in the uf.h header file ).
Because internal Open C API programs are running
in an NX environment, part display is automatically done. Object display can be
suppressed and individual objects displayed with routines in the uf_disp.h header file such as UF_DISP_set_display
and UF_DISP_add_item_to_display.
Under certain circumstances in Internal Open C API, a part must be active (e.g.
geometry creation). The active part may be one that was previously opened
interactively in NX or one retrieved in Open C API. UF_ASSEM_ask_work_part
can be used to determine if a part is already active. Parts can be filed either
from Open C API or in NX.
External C programs use the standard C main
function to call Open C API routines. See ext_uf_example.c
in your installed Open C API directory for for an
example external program.
External Open C API programs are written, compiled, and linked like any normal
program. Program statements for start up and termination should follow those
normal for "C".
All terminal I/O should be done using the I/O
statements supplied by the high-level language (e.g. C functions puts(), getchar(), printf(), etc.).
If the External Open C API program is invoked from NX running on a terminal
with windows, all high-level language I/O will appear on the window from which
NX was started. This window may be hidden behind some of the other NX windows
and must be "popped" to the top to be used. On Windows NT, there is
not a terminal window associated with NX, so terminal I/O is not possible.
No part display can or will be done in external
mode. Any part created or modified by external Open C API programs will have to
be retrieved in NX for display after the external Open C API has filed the
part.
Before any Database routines can be called, an existing part must be created or
retrieved (UF_PART_new or UF_PART_open)
to work on. Parts can be filed with UF_PART_save, UF_PART_save_as, or UF_PART_save_all.
Unless otherwise noted, new Open C API functions
are written in C and follow the ANSI C standard. Please refer to the Release
Letter for information on new functionality and changes.
Except where noted, all new Open C API functions follow a descriptive naming
convention. The format is:
UF_ABBR_descriptive_name
where:
UF_ denotes Unigraphics Open C API Function
ABBR_ is the abbreviation for the area the function represents
descriptive_name is a descriptive title giving a hint
of the function's purpose
As an example:
UF_PART_close_all A function that falls into
the part manipulation application that closes all open parts.
The Open C API has a large set of routines to
create and modify NX objects. We assume that you are familiar enough with NX and
the C language to prevent any serious mistakes. Some of the routines return an
error code, others do not. The routines that create objects will return an
Object Identifier = NULL_TAG to indicate an error.
Open C API supports all C data types. Object
Identifiers (EIDs) should be declared as tag_t to
limit changes to your program.
Character strings vary in length. The lengths documented in this manual are the
maximum number of characters of data that are valid for either input or output
by the routine.
Many routines require data structures. In most
cases the data structures are documented in the header file. However, there are
some instances where a data structure is for internal use only or for
proprietary usage and only a pointer to that structure is declared for the
user.
Ths documentation is organized by the header file that prototypes the
functions. There are several include files provided for the users to add to their
programs. The users should include uf_defs.h for
general typedefs. The other include files should be
used depending on the users application. These include files contain typedef declarations, ANSI prototypes of new routines and
legacy code, and macros pertinent to the specified application.
Unless otherwise documented, every routine
returns an int, which is the error code. A return
code of 0 indicates success, and any other number indicates failure. The
message associated with an error code can be retrieved by calling UF_get_fail_message.
In Unigraphics V9, when an object had a known
object Identifier (EID), that EID was saved with the part and would be the same
the next time the part was loaded. In V10 and beyond, because multiple parts
can be loaded at once, the Tag (i.e. EID) of an object cannot be guaranteed
between sessions. For this reason, "handles" were created to identify
entities between sessions. To aid applications where the EID was saved in some
data file between sessions, UF_ask_new_tag_of_object was created to return the
post-V10 tag corresponding to the EID of an object in a V9 part that was just loaded.
That tag can then be converted to a post-V10 handle using UF_TAG_ask_handle_of_tag.
Some Open C routines have been targetted to be removed from the released Open C libraries.
Most of these routines are older routines that were originally used to support
FORTRAN code. The legacy Removal Document
lists these routines, and has information required to let almost all existing
programs work without source code changes.
You execute Open C API programs by selecting the
file name. After you have successfully compiled and linked your Open C API
program perform the following steps:
From within NX select File-->Execute-->NX Open. A list box displays the
executable that you have previously successfully compiled and linked. If you
execute externally written programs from within an NX session you cannot pass a
command line argument. Additionally, you cannot perform operations on your
current interactive part. You may wish to execute your external programs from
the command line for these reasons.
Ufmenu is a utility script/command file that provides you with the
ability to edit, compile, link and run your Open C API programs. ufcomp is a script that gives you
the ability to compile programs, and uflink is a
script that gives you the ability to link programs. These scripts are only
supported on Linux and Macos workstations. See ufmenu details, ufcomp details and uflink details for more
information.
On on system that are
not windows based systems , you can copy a template makefile (ufun_make_template.ksh) located in the
${UGII_BASE_DIR}/ugopen directory, to compile and
link your programs.
The template makefile can be customized to compile
and link: both internal and external, internal only,
or external only Open C API programs. Instructions on how to use the template
file are fully explained in the commented section of the file.
After you have customized the template file, you should copy or move the file
so that it is named either "Makefile" or
"makefile", which are the standard names
the make command expects. Alternatively, you could use the "-f"
switch with the make command to specify the makefile
name.
The template makefile was designed to be used with
the make command supplied by the platform's vendor. For further information on
make and file dependencies use "man make".
This section describes the machine dependent
information on how to setup and use Open C on your system. To use the Open C
API, you must have the C or C++ environment setup on your workstation. If this
environment is not set up, your system administrator must install it. For
further details see:
Windows Operating System Setup
Linux Setup
The table listing the compilers for each
supported platform can be found in the Product Notes under Automation. NX does
not certify any other compilers for use with Open C programs. In general, the
platform vendors must address any problems with a compiler newer than that
which built NX. (See the Release Notes for OS levels that NX does certify.)
Occasionally vendors obsolete compilers or create new compilers that are
incompatible with the version that built NX. NX has no control over such developments,
although the vendors usually have a vested interest in ensuring that newer
compilers are compatible with the older versions.