NX UGOPEN函数参考手册

Overview

Open C API is designed to enable an easy interface between NX and the outside world. The Open C API consists of:

? a large set of user callable functions/subroutines that access the NX Graphics Terminal, File Manager, and Database.

?command procedures to link and run user programs.

?an interactive interface in NX to run those programs.

Open C API programs can run in 2 different environments, depending on how the program was linked. The two environments are:

?External - these Open C API programs are stand alone programs that can run from the operating system, outside of NX, or as a child process spawned from NX.

?Internal - these Open C API programs can only be run from inside of an NX session.

These programs are loaded into main memory along side of NX and access routines

within NX. One advantage to this is that the executables are much smaller and link

much faster. Once an Internal Open C API Program is loaded into memory, it can stay resident for the remainder of the NX session. If you call this program again, it executes without reloading (provided it was not unloaded). Internal Open C API programs work on the current part and automatically modify the part display.

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

(GR aphics I nteractive P rogramming) 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.

Example Source Code Files

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.cis 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.

Supported Languages

Open C API programs can be written in the C or C++ programming languages.

Initialization and Termination

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_initializeonce.

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 andUF_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 https://www.360docs.net/doc/a515929389.html,. 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.

Function Requirements

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.

Internal Programs

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

/* 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 ).

Automatic Part Display

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 Programs

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".

External Model Terminal I/O

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

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

withUF_PART_save, UF_PART_save_as, or UF_PART_save_all.

Open C API Conventions

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 U nigraphics Open C API F unction

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.

Database Routines

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.

Variable Declarations

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.

Data Structures

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.

Include Files

This 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 typedefdeclarations, ANSI prototypes of new routines and legacy code, and macros pertinent to the specified application.

Error Codes

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.

Handles

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.

Legacy Routines

Some Open C routines have been targeted 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.

How to Execute Programs

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.

Compiling and Linking on Linux/Macos Systems

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.

Compiling and Linking with a Linux Makefile

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".

Setting up your system

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

Compiler Certification

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.