IntegrationToolkitProgrammerGuide_V10

(1)

Teamcenter

®

2005 SR1

engineering process management

Teamcenter Engineering

Integration Toolkit Programmer’s

Guide

(2)

(3)

Teamcenter

®

2005 SR1

engineering process management

Teamcenter Engineering

Integration Toolkit Programmer’s

Guide

This product is intended for use only described in this document. UGS cannot be responsible for the proper functioning of undescribed features and parameters.

(4)

Manual History

Manual Revision Teamcenter Engineering Version Publication Date A 2005 SR1 June 2006

(5)

Format . . . 5-1 Variable Naming Conventions . . . 5-3 Class Hierarchy . . . 5-3 Debugging . . . 5-4 Error Handling . . . 5-7 Memory Management . . . 5-10 Include Files . . . 5-10 Initializing Modules . . . 5-12 Special Data Types . . . 5-12 Compiling . . . 5-13 Linking Standalone Programs . . . 5-13 Running the Executable . . . 5-20 Batch ITK . . . 5-21

(6)

Contents

Part II: ITK Modules

Core Functions . . . 6-1

Core Classes . . . 6-1 File Relocation . . . 6-26 Changing the Revisioning Scheme . . . 6-28 Types, Properties, and Methods . . . 6-29

System Administrator . . . 7-1

List of Values . . . 7-1 Access Manager . . . 7-2 Audit Manager . . . 7-4 Business Modeler . . . 7-5

Product Structure Management . . . 8-1

Bill of Materials (BOM) Module . . . 8-1 BOM Compare Functions . . . 8-14 Product Structure (PS) Module . . . 8-34 Product Structure Model . . . 8-41

Persistent Object Manager Layer . . . 9-1

Persistent Object Manager . . . 9-1 POM Inheritance Example . . . 9-24 POM Enquiry Module . . . 9-33

Workflow . . . . 10-1

Enterprise Process Modeling . . . 10-1 EPM Object Model . . . 10-2 Customizing a Procedure With EPM . . . 10-7 EPM Hints . . . 10-18 Cascade Release Hints . . . 10-20

Data Sharing of Data Objects . . . . 11-1

Object Import and Export . . . 11-1 Multi-Site Collaboration . . . 11-7

Customizing Forms and Properties Display . . . . 12-1

Communication With the Server . . . 12-2 Form UI Display Components . . . 12-2 Displaying a Form . . . 12-3 Teamcenter Engineering Form Types . . . 12-4 Developing Automatic Forms . . . 12-5

(7)

Contents

Customizing Text and Error Messages . . . . 13-1 Mechatronics . . . . 14-1

Mechatronics Fundamental Objects . . . 14-1 Object Model . . . 14-3 Harness Model Support . . . 14-4 Mechatronics API Modules . . . 14-4 API Use Examples . . . 14-5 Embedded Software Manager . . . 14-15

Traversal Engine . . . . 15-1

Basic Features . . . 15-1 User Exits . . . 15-2 Minimum Requirements . . . 15-2 Installation . . . 15-2 Developing a Traversal Program . . . 15-3 Sample Implementation . . . 15-3

Glossary . . . A-1 Index . . . Index-1

Figures

2-1. Four-Tier Architecture . . . 2-1 4-1. Class Object Diagram Legend . . . 4-1 4-2. Item/Item Revision Model . . . 4-2 4-3. Dataset Model . . . 4-7 4-4. Form Model . . . 4-8 4-5. System Administration Model . . . 4-8 4-6. Access Control Model . . . 4-9 4-7. Class Hierarchy . . . 4-12 5-1. Journal File Example 1 . . . 5-4 5-2. Journal File Example 2 . . . 5-5 5-3. Journal File Example 3 . . . 5-6 5-4. Gateway Response Example . . . 5-8 5-5. Code Template to Fix Invalid Characters . . . 5-9 5-6. user_server_exits.c File Example . . . 5-17 5-7. Java Code Example . . . 5-19 5-8. Batch Program Template . . . 5-22 5-9. Register Custom Callbacks Example . . . 5-25 5-10. User Exits Customization Example . . . 5-27 5-11. Server Exits Customization Example . . . 5-28 5-12. Registering a Custom Handler in a Custom Exit Example . . . 5-33 5-13. Sample Registration of Property Methods . . . 5-34 6-1. Teamcenter Object Model . . . 6-31 6-2. Property Method Inheritance . . . 6-37 6-3. Canned Methods Example . . . 6-47 6-4. Property File Entries . . . 6-49

(8)

Contents

6-6. Adding an Attribute to a New Subclass . . . 6-54 6-7. Adding a Property From a Relation . . . 6-55 6-8. Adding a Runtime Property . . . 6-56 7-1. Partial Listing of the am_text.xml File . . . 7-2 7-2. bmf_extension_workflow_sample.h Include File . . . 7-7 7-3. bmf_extension_workflow_sample.c Source File . . . 7-12 8-1. Sample BOM Program . . . 8-8 8-2. Runtime Options . . . 8-12 8-3. Single Level Compare . . . 8-17 8-4. Compare Report Code . . . 8-20 8-5. Property Display Element Definition . . . 8-21 8-6. Display Order Definition . . . 8-23 8-7. Traversing Example . . . 8-27 8-8. BOM Compare Visitor 1 . . . 8-32 8-9. BOM Compare Visitor 2 . . . 8-33 8-10. BOMView Class Attributes and Methods . . . 8-34 8-11. BOMView Revision Class Attributes and Methods . . . 8-36 8-12. Occurrence Class Attributes and Methods . . . 8-38 8-13. View Type Class Attributes and Methods . . . 8-39 8-14. Note Type Class Attributes and Methods . . . 8-40 8-15. Product Structure Model . . . 8-41 8-16. Item Revision Model . . . 8-42 9-1. Classes . . . 9-2 9-2. Initial Classes . . . 9-5 9-3. Class Hierarchy . . . 9-8 9-4. folderlib.h . . . 9-25 9-5. Schema Definition . . . 9-27 9-6. ITK Extension . . . 9-32 9-7. Basic Single Table Enquiry Example . . . 9-36 9-8. Simple Join . . . 9-37 9-9. Simple Join Example . . . 9-38 9-10. Practical Example . . . 9-42 9-11. SELECT POM Enquiry APIs . . . 9-43 9-12. WHERE POM Enquiry APIs . . . 9-44 9-13. ORDER BY POM Enquiry APIs . . . 9-46 9-14. Subquery POM Enquiry APIs . . . 9-48 9-15. class_alias POM Enquiry APIs . . . 9-50 9-16. pseudo_class POM Enquiry APIs . . . 9-52 9-17. Set-Expression INTERSECTION POM Enquiry APIs . . . 9-53 9-18. Set-Expression DIFFERENCE POM Enquiry APIs . . . 9-54 9-19. Set-Expression UNION POM Enquiry APIs . . . 9-56 9-20. SUBSTR POM Enquiry APIs . . . 9-57 9-21. cpid POM Enquiry APIs . . . 9-58 9-22. UPPER and LOWER POM Enquiry APIs . . . 9-59 9-23. COUNT POM Enquiry APIs . . . 9-60 10-1. Task Model . . . 10-1 10-2. Task Model Table . . . 10-2 10-3. EPM Object Model . . . 10-2 10-4. Module Initialization Function Example . . . 10-12 10-5. Validation Rule File Example . . . 10-16

(9)

Contents

11-1. Export Route . . . 11-3 11-2. Import Route . . . 11-5 12-1. Form Model . . . 12-2 12-2. Form UI Display Panel . . . 12-2 12-3. Form Displayed in a Dialog . . . 12-3 12-4. Form Displayed in the Rich Client Viewer . . . 12-3 12-5. Form Type Definition . . . 12-6 12-6. Basic UI Form and Components . . . 12-7 12-7. UI Definition . . . 12-9 12-8. Style Sheet Viewer . . . 12-18 12-9. XML Definition Example . . . 12-19 12-10. Form Rendering Example . . . 12-19 12-11. Form Rendering Example . . . 12-20 12-12. XML File Elements . . . 12-20 12-13. OneColumn Display Format . . . 12-26 12-14. TwoColumn Display Format . . . 12-26 12-15. Headed Rendering Style . . . 12-26 12-16. Titled Rendering Style . . . 12-26 12-17. User Properties XML Definition . . . 12-30 12-18. User Properties Dialog . . . 12-31 12-19. Item Properties XML Definition . . . 12-32 12-20. User Properties Dialog . . . 12-33 12-21. PropertyNameLabel . . . 12-33 12-22. PropertyTextField . . . 12-34 12-23. TitledPropertyTextField . . . 12-34 12-24. PropertyTextArea . . . 12-35 12-25. TitledPropertyTextArea . . . 12-35 12-26. PropertyButton . . . 12-36 12-27. TitledPropertyButton . . . 12-36 12-28. TitledPropertyLabel . . . 12-37 12-29. PropertySlider . . . 12-37 12-30. TitledPropertySlider . . . 12-38 12-31. PropertyDateButton . . . 12-38 12-32. TitledPropertyDateButton . . . 12-39 12-33. PropertyCheckbox . . . 12-39 12-34. TitledPropertyCheckbox . . . 12-40 12-35. PropertyRadioButton . . . 12-41 12-36. TitledPropertyRadioButton . . . 12-41 12-37. PropertyToggleButton . . . 12-42 12-38. TitledPropertyToggleButton . . . 12-42 12-39. LOVPopupButton . . . 12-43 12-40. TitledPropertyLOVButton . . . 12-43 12-41. PropertyLOVPopupButton . . . 12-44 12-42. TitledPropertyLOVCombobox . . . 12-44 12-43. PropertyCheckboxOptionLov . . . 12-45 12-44. TitledPropertyCheckboxOptionLov . . . 12-45 12-45. PropertyRadioButtonOptionLov . . . 12-45 12-46. TitledPropertyRadioButtonOptionLov . . . 12-46 12-47. PropertyToggleButtonOptionLov . . . 12-46 12-48. TitledPropertyToggleButtonOptionLov . . . 12-46 12-49. PropertyObjectLink . . . 12-47 12-50. TitledPropertyObjectLink . . . 12-47 12-51. PropertyLongText . . . 12-48

(10)

Contents 12-52. TitledPropertyLongText . . . 12-49 12-53. TitledPropertyLogicalPanel . . . 12-49 12-54. PropertyArray . . . 12-51 12-55. TitledPropertyArray . . . 12-51 12-56. PropertyImage . . . 12-52 14-1. Object Model . . . 14-3 14-2. Climate Control System . . . 14-5 14-3. Defining Port Example . . . 14-6 14-4. Functionality Connections . . . 14-7 14-5. Creating Connections . . . 14-8 14-6. Embedded Software Manager Example . . . 14-19

Tables

8-1. Variant Expression Operators . . . 8-10 9-1. POM Enquiry Functions . . . 9-40 9-2. Supported Operators . . . 9-61 11-1. Process and Data Flow . . . 11-7 12-1. Modified Components in Read-Only Forms . . . 12-12 12-2. XML Elements and Attributes . . . 12-21 12-3. JavaBeans Based on Rendering Hint and Style . . . 12-27 12-4. Default Renderers . . . 12-29 14-1. Mechatronics Objects . . . 14-1 14-2. Embedded Software Manager Functions . . . 14-15 14-3. Signal Manager Functions . . . 14-17

(11)

Preface

This manual describes how to use the Integration Toolkit to customize Teamcenter® Engineering. Teamcenter Engineering belongs to the UGS® portfolio of digital product lifecycle management software and services.

This document supplements the Teamcenter Engineering Help Library. If you find information inconsistent with that found in that Teamcenter

Engineering Help Library, contact the UGS Global Technical Access Center

(GTAC) for clarification.

Audience

The readers of this guide should be experienced Teamcenter Engineering system administrators and programmers.

Organization

This manual contains the following chapters and appendixes:

Chapter 1 Introduction to Integration Toolkit Programmingdefines the Integration Toolkit and describes the two parts of the manual.

Chapter 2 Architecture Overviewdescribes the software architecture of Teamcenter.

Chapter 3 Application Interfaces briefly describes the application interfaces you can use to integrate external applications with Teamcenter Engineering.

Chapter 4 Teamcenter Object Modelbegins with a brief description of objects in general, then progresses to a discussion of the Teamcenter Object Model. It also provides information on the various objects used in the Teamcenter system and how they are related.

Chapter 5 Using ITK Functionsdescribes the format of ITK functions as well as details about writing, compiling, linking, and running ITK programs.

Chapter 6 Core Functions describes the modules that contain Teamcenter’s core functionality.

(12)

Preface

Chapter 8 Product Structure Managementdescribes the modules that contain product structure management functionality. Chapter 9 Persistent Object Manager Layerdescribes the Persistent

Object Manager (POM), POM inheritance, and the POM enquiry module.

Chapter 10 Workflowdescribes the Enterprise Process Modeling (EPM) module and the Cascade Release (CR) application.

Chapter 11 Data Sharing of Data Objectsdescribes how to import and export objects and Multi-Site Collaboration programming techniques.

Chapter 12 Customizing Forms and Properties Display describes the processes used to create forms in the Teamcenter Engineering rich client.

Chapter 13 Customizing Text and Error Messagesdescribes how to customize text and error messages.

Chapter 14 Mechatronicsprovides background information required to use ITK APIs to create and manipulate Mechatronics objects.

Chapter 15 Traversal Enginedescribes the Traversal Engine module that allows you to develop utilities that traverse Teamcenter Engineering structures, such as Product Structure (PS), without needing to write a specific program.

(13)

Preface

Conventions

This manual uses the conventions described in the following sections.

Note, Caution, and Warning Icons

The following icons represent note, caution, and warning messages:

A note icon identifies general instructions or comments that need to be emphasized.

A caution icon identifies practices that can either produce results contrary to what you expect or result in damage to software or data.

A warning icon identifies practices that could result in permanent loss of data or software.

Names and Values

This manual represents system names, file names, and values in fonts that help you interpret the name or value. For example:

The file name is pom_schema_server-name_sid. The conventions are:

Bold Bold font represents unvarying text or numbers within a name or value. Capitalization is as it appears.

In the preceding example, pom_schema_ identifies an unvarying portion of the name.

Italic Italic font represents text or numbers that vary. The characters in italic text describe the entry. Letters are shown in lowercase, but the varying text may include uppercase letters.

In the preceding example, server-name and sid represent varying portions of the name.

text-text A hyphen separates two words that describe a single entry. In the preceding example, server-name is a single value. For example, the name of the pom_schema_server-name_sid file may be:

(14)

Preface

Command Line Entries, File Contents, and Code

This manual represents command line input and output, the contents of system files, and computer code in fonts that help you understand how to enter text or to interpret displayed text. For example, the following line represents a command entry:

create_change_types -u=user-name -p=password -g=group -f=file-name

The conventions are:

Monospace _{Monospace font represents text or numbers you enter on a}

command line, the computer’s response, the contents of system files, and computer code.

Capitalization and spacing are shown exactly as you must enter the characters or as the computer displays the characters. In the preceding example, create_change_types identifies an

unvarying portion of the command.

Italic _{Italic font represents text or numbers that vary. The words in}

italic text describe the entry.

The words are shown in lowercase letters, but the varying text may include uppercase letters. When entering text, use the case required by the system.

In the preceding example, user-name, password, group, and

file-name identify varying portions of the command.

text-text A hyphen separates two words that describe a single entry.

In the preceding example, user-name is a single entry in the command.

The following example is a correct entry for the preceding create_change_types command:

(15)

Preface

Syntax Definitions

This manual uses a set of conventions to define the syntax of Teamcenter commands, functions, and properties. Following is a sample syntax format:

harvester_jt.pl [bookmark-file-name bookmark-file-name ...]

[directory-name directory-name ...] The conventions are:

Bold Bold text represents words and symbols you must enter exactly as shown.

In the preceding example, you enter harvester_jt.pl exactly as shown.

Italic Italic text represents values that you supply.

In the preceding example, you supply values for bookmark-file-name and directory-name.

text-text A hyphen separates two words that describe a single value. In the preceding example, bookmark-file-name is a single value. [ ] Brackets represent optional elements.

... An ellipsis indicates that you can repeat the preceding element. Following are examples of correct syntax for the harvester_jt.pl: command:

harvester_jt.pl

harvester_jt.pl assembly123.bkm

harvester_jt.pl assembly123.bkm assembly124.bkm assembly125.bkm harvester_jt.pl AssemblyBookmarks

(16)

Preface

Teamcenter Engineering Documentation

Teamcenter Engineering documentation is provided as online help and as printable manuals:

• You can access online help by choosingHelp from the menu bar of a Teamcenter Engineering rich client application or by clicking one of the links under theHelp icon in the Teamcenter Engineering thin client user interface.

• You can access the printable manuals from the Teamcenter Engineering Documentation CD-ROM. To view the PDF-formatted manuals, use Adobe Acrobat Reader, downloadable free-of-charge from Adobe Systems Incorporated at the following URL:

http://www.adobe.com

Acrobat Reader allows you to view these manuals online and print selected pages, sections, or the entire manual. UGS grants permission for Teamcenter Engineering users to print, duplicate, and distribute this documentation.

Submitting Comments

Portions of Teamcenter software are provided by third-party vendors. Special agreements with these vendors require UGS to handle all problem reports

concerning the software they provide. Please submit all comments directly to UGS. Please feel free to give us your opinion of the usability of this manual, to suggest specific improvements, and to report errors. Mail your comments to:

UGS Technical Communications 4233 Lexington Avenue N., Suite 3290 Arden Hills, MN 55126-6198

U.S.A.

To submit an incident report, you can use the UGS GTAC online support tools at the following URL:

http://support.ugs.com

Software Copyright and Trademark Notices

UGS and Teamcenter are registered trademarks or trademarks of UGS Corp. or its subsidiaries in the United States and in other countries.

Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

(17)

Chapter

1 Introduction to Integration

Toolkit Programming

(18)

(19)

Chapter

1 Introduction to Integration

Toolkit Programming

This chapter defines the Integration Toolkit and describes the two parts of the manual.

UGS is committed to maintaining compatibility between Teamcenter product releases. If you customize functions and methods using published APIs and documented extension points, be assured that the next successive release will honor these interfaces. On occasion, it may become necessary to make behaviors more usable or to provide better integrity. Our policy is to notify customers at the time of the release prior to the one that contains a published interface behavior change.

UGS does not support code extensions that use unpublished and undocumented APIs or extension points. All APIs and other extension points are unpublished unless documented in the official set of technical manuals and help files issued by UGS Technical Communications.

The Teamcenter license agreements prohibit reverse engineering, including: decompiling Teamcenter object code or bytecode to derive any form of the original source code; the inspection of header files; and the examination of configuration files, database tables, or other artifacts of implementation. UGS does not support code extensions made using source code created from such reverse engineering.

If you have a comment or would like to request additional extensibility, contact the UGS customer support representatives at GTAC for further assistance.

The Integration Toolkit (ITK) is a set of software tools that you can use to integrate third-party or user-developed applications with Teamcenter. The ITK is a set of C and C++ functions used directly by Teamcenter and NX.

The Integration Toolkit is a set of callable subroutines that act as a programmatic interface to Teamcenter. It is the means by which both internal and external applications interface with the Teamcenter core (including RDBMS) and the Teamcenter front end (including the window management subsystem). Internal applications are those supplied such as NX. External applications are those that you decide to integrate into Teamcenter.

(20)

Chapter 1 Introduction to Integration Toolkit Programming

Teamcenter consists of various modules. The ITK interfaces the integrator’s application to these modules. The end goal of the ITK is to fully integrate an application into Teamcenter.

The topics in this manual provide the background information necessary for you to understand the Teamcenter philosophy, architecture, and object model.

Refer to the Teamcenter Engineering Release Bulletin for a list of supported compilers.

This manual is divided into two parts: 1. ITK Concepts

This part gives an overview of the Teamcenter architecture and the application interfaces you can use to interact with it.

2. ITK Modules

This part describes the Teamcenter modules where you can use ITK to customize your Teamcenter application.

General Caveats and Restrictions

Teamcenter reserves command line switches beginning with –z for internal use. Therefore, ITK programs should avoid the use of switches which begin with –z.

The dataset_cleanup utility fails to print out trailing information about the log file after it finishes processing anchors before it exits to the prompt. On Windows, you do not know if it ended correctly or the location of the log file. Also, it does not delete anchors with zero size.

This applies to all ITK programs, not those only involving datasets. The problem can be resolved by setting the IMAN_KEEP_SYSTEM_LOG environment variable to 1.

(21)

Part

I

ITK Concepts

This part describes the basic concepts you should be familiar with to customize Teamcenter with ITK.

Architecture Overview . . . 2-1 Application Interfaces . . . 3-1 Teamcenter Object Model . . . 4-1 Using ITK Functions . . . 5-1

(22)

(23)

Chapter

2 Architecture Overview

Client Tier . . . 2-2 Web Tier . . . 2-2 Enterprise Tier . . . 2-2 Resource Tier . . . 2-2

(24)

(25)

Chapter

2 Architecture Overview

This chapter describes the software architecture of Teamcenter.

Teamcenter is constructed in tiers. The lowest tiers are closest to the database and file volumes and the highest tiers are closest to the user. The Teamcenter architecture consists of the following tiers:

• Client tier • Web tier • Enterprise tier • Resource tier

Figure 2-1. Four-Tier Architecture

These layers run on top of, and add functionality to, existing host facilities instead of replacing host facilities. For example, Teamcenter interfaces to the host electronic mail facilities, but also provides a higher level of messaging to overcome certain

(26)

Chapter 2 Architecture Overview

Client Tier

The client tier comprises the Teamcenter Engineering clients: the thin client and rich client. For more information, see the Thin Client Help - DHTML and the Rich

Client Customization Programmer’s Guide.

Web Tier

The Web tier is a Java application that runs in a Java 2 Enterprise Edition (J2EE) application server, such as BEAWebLogic, and is responsible for communication between the client tier and enterprise tier. The Web tier application also includes the Application Interface Web Service (AIWS) and Teamcenter Engineering Data Integration Services Adapter.

Enterprise Tier

The enterprise tier comprises a configurable pool of Teamcenter Engineering C++ server processes and a server manager. The enterprise tier retrieves data from and stores data in the database. A server manager manages a pool of Teamcenter Engineering server processes. This is the tier where you use ITK programming to customize Teamcenter Engineering on the server side.

Resource Tier

The resource tier comprises a database server, database, volumes, and file servers with two file management systems.

• The Teamcenter File Management System (FMS) downloads and uploads file data for the rich client, Teamcenter Visualization, and the thin client configured with Teamcenter Visualization. It provides a file storage, caching, distribution, and access system. Multi-Site Collaboration also uses FMS servers to transfer data.

• Teamcenter File Services (TCFS) is a legacy file management system, previously called IMANFS, that provides a variety of volume-related services and operates in conjunction with the File Management System (FMS). The Teamcenter Engineering Organization application uses TCFS to create volumes and perform other administrative functions. TCFS also supports file access for NX 4.0.1 or earlier and Teamcenter Visualization 5.0 or earlier when you use these products with Teamcenter Engineering. (NX 4.0.2 and Teamcenter Visualization 6.0 and later use File Management System.)

• For more information about supported databases, see the Teamcenter

(27)

Architecture Overview

There are three ways to read, edit, or create data in Teamcenter: • interactively

• import/export • programmatically

Interactive access is accomplished through the forms and menus or through the interactive dialogues of applications integrated within Teamcenter. Import/export involves taking the data out of Teamcenter, accessing the data by any means at your disposal and later, putting data back into the Teamcenter system. ITK also provides programmatic access.

You accomplish file access through the ImanFile interface of the ITK when this is available through TCFS. For FMS-based file access, use the FMS ITK interface. You can use the file management functions in this module to interface into the operating system I/O utilities.

The information in the database is stored in tables in a relational database and is accessed using SQL. Only the POM should ever read from, or write data directly to, Teamcenter tables. Other application programs can create and access their own tables directly.

The POM is the tool that we provide for internal programmers, third parties, and customers to define their own data types, create and access their own data, and access simple Teamcenter data. To define data types, you normally use administrative applications in the rich client, such as Schema Editor, Type, or Business Modeler, rather than directly editing schemas or writing code (for more information about these applications, see Schema Editor Help, Type Help, and

Business Modeler Help). It also presents an object-oriented view of data, rather than

the tabular view that SQL presents. Finally, it implements the locking, checking of access rights, and referential integrity checks for the system.

At the highest semantic level, there are application level procedures for accessing data. These procedures can potentially operate on many objects at once, and can perform tasks other than just simple data reads and writes.

For example, an ITK procedure to add an attribute to a Configuration Management (CM) object can actually cause a new object to be created in the database. References must be added from this new object to the CM object and vice versa. Several POM calls must be made to build a valid set of data. Those POM calls make even more use of SQL to finally speak to the relational database in its terms of tables, rows and values. In general, the POM should not be used to access object data for which there are higher level ITK procedures.

(28)

(29)

Chapter

(30)

(31)

Chapter

3 Application Interfaces

This chapter briefly describes the application interfaces you can use to integrate external applications with Teamcenter Engineering.

There are five application interfaces you can use to integrate external applications with Teamcenter Engineering:

• Service-Oriented Architecture (SOA)

SOA allows different applications to communicate with one another using services. SOA is appropriate for integrating separate applications with a loose linkage and network-friendly APIs that do not need to be modified with every release of Teamcenter Engineering. This is the preferred method of integrating third party and client applications. Future releases will extend this interface and provide tools so you can easily extend it. For more information about SOA, see the Web Services Guide.

• Integration Toolkit (ITK)

Use the ITK interface when programming within the Teamcenter server (for example, extension points, workflow handlers, or low-level batch programs) and when constructing new interfaces for SOA. It is a low level interface that normally requires many more calls than the higher level interfaces (SOA, Application Interface Web Service, Application Integration Environment) to execute a given action, but it is powerful when you need to access the system in this way. For integrating external applications, UGS recommends that you use SOA. If you need functionality not exposed using SOA, then write new, high-level service methods using ITK and expose them as SOA interfaces using the SOA toolkit.

• Application Interface Web Service (AIWS)

AIWS allows Teamcenter Engineering and an external application to share data that exists in the same context. To communicate with an external application, you must create and install an AIWS proxy client in the external application. You can use only AIWS for some kinds of integrations, but SOA will eventually replace AIWS. You should use AIWS only if no other interface supplies the functionality you need and you cannot extend SOA with ITK as described. For more information about AIWS, see the Application Interface Web Service (AIWS)

(32)

Chapter 3 Application Interfaces

• Application Integration Environment (AIE)

AIE provides the framework and common functions required to integrate applications with Teamcenter. AIE is similar to AIWS and it is the only choice when working with some CAD integrations. You should use AIE only if no other interface supplies the functionality you need and you cannot extend SOA with ITK as described above. For more information about AIE, see the Application

Integration Environment Help

• Generic Shell

Generic Shell is a mechanism that Teamcenter Engineering uses to encapsulate an application. Generic Shell intercepts application save commands and saves data files in Teamcenter Engineering volumes instead of directly in the operating system file structure. Generic Shell is appropriate for some kinds of very simple integrations, and you can avoid programming altogether if you use this interface carefully.

The user_edshell.c file in the /sample/examples directory shows how to integrate an application into Teamcenter using the Generic Shell, in this case an ASCII text editor. You can use the Teamcenter ITK to develop a new application that is fully integrated with Teamcenter or it can be used to develop a shell for an existing application.

(33)

Chapter

4 Teamcenter Object Model

Object Model . . . 4-1 Product Structure Object Model . . . 4-1 Item and Item Revision Model . . . 4-1 Item . . . 4-2 Item Revision . . . 4-3 Relations . . . 4-3 Modifying an Item/Item Revision . . . 4-6 Item Type . . . 4-6 Dataset Model . . . 4-7 Unique ID Enforcement . . . 4-7 Form Model . . . 4-7 System Administration Model . . . 4-8 Access Control Model . . . 4-9 Application Encapsulation Model . . . 4-9 Class Hierarchy . . . 4-11 Object-Oriented Data . . . 4-13 Inheritance . . . 4-13 Object-Oriented Language . . . 4-14

(34)

(35)

Chapter

4 Teamcenter Object Model

This chapter begins with a brief description of objects in general, then progresses to a discussion of the Teamcenter Object Model. It also provides information on the various objects used in the Teamcenter system and how they are related.

Object Model

The model is described using a set of two basic relationship diagrams. One set of relationships show the class hierarchy (taxonomy) and the other shows the associations that exist between interacting objects in the system.

This is the legend for the class object diagrams that follow.

Figure 4-1. Class Object Diagram Legend

Product Structure Object Model

For detailed information on the Product Structure object model, seeProduct Structure (PS) Module.

Item and Item Revision Model

Figure 4-2 shows an illustration of an item/item revision model. The textual definitions that follow correspond to the objects of that model type.

(36)

Chapter 4 Teamcenter Object Model

Figure 4-2. Item/Item Revision Model Item

In Teamcenter, items are the fundamental objects used to manage information. Items provide an identification for physical or conceptual entities about which an organization maintains information and audit/change control. Typical uses of items are parts, documents, and equipment. In an engineering/product development environment, parts are identified as items. An item has the following basic information:

• ID

A unique identifier for an item. • Name

A user defined name to describe the item. • Type

A classification of items that allow different types of items to be treated separately. For example, an item may be used to manage parts and equipment. By implementing two item types, rules can be enforced based on the type of

(37)

Teamcenter Object Model

• Description

A text field of up to 240 characters used to describe the item.

Item Revision

Item revisions are used to reflect modifications to an item. The original item revision is retained for historical purposes.

Each customer site defines its own procedures to determine how and when a new item revision should be created.

An item revision has the following basic information: • ID

A unique identifier for an item.

• Revision

A unique identifier for an item revision. • Name

A user-defined name to describe the item revision.

Relations

Organizations produce several documents that describe, are used by, or in some way relate to an item. For the data to be understood, it has to be associated in a meaningful way to the item or item revision. Teamcenter associates data to items and item revisions using relations.

Relations describe how the data is associated to an item and item revision. A dataset containing the CAD model, which defines an item revision, is a specification of the item revision. Similarly, a standards document describing the fit, form, and function of a particular drawing is a requirement for the item.

An item or item revision can be related to several other objects, including datasets, forms, folders, and other items and item revisions. Each object associated to the item represents various aspects of that item. A dataset containing stress test information could be added by the engineer, while a form containing size and weight information could be added by the specification engineer.

Teamcenter provides a basic set of relations. The relations between the object and the item and item revision determines the rules enforced.

Additional relations and their associated rules are defined by your system administrator.

• Master_form

The master_form relation associates a form to an item or item revision. This form is a collection of attributes that describe the item or item revision. Rules for this relation are as follows:

(38)

– Only a form can have a master_form relation to an item or item revision. – An item can have only one master form. An item revision can have only

one master form.

– A form can have a master_form relation to only one item or item revision.

• Requirement

The requirement relation associates data to an item or item revision, such as standards, which must be adhered to in a drawing, or technical requirements for a part. Rules for this relation are as follows:

– An item or item revision must have write access to add or remove a

requirement relation to an object.

– A form can have a requirement relation to an item or item revision. – Only version 0 (zero) of a dataset can have a requirement relation to an

item or item revision.

– A folder, envelope, BOMView, or BOMView Revision cannot have a

requirement relation to an item or item revision.

– An item cannot have a requirement relation to another item or item revision.

– An item revision can have a requirement relation to another item or item revision.

– An item revision cannot have a requirement relation to another item revision if they are both revisions of the same item.

• Manifestation

The manifestation relation associates other related data to an item or item revision. This data may, however, be necessary for information, such as analysis of the competing ideas from which a part was originally conceived. The

manifestation relation also associates data to the item revision that contains

data derived from the specification data (such as tool paths). Rules for this relation are as follows:

– An item or item revision does NOT need to have write access to add or remove a manifestation relation to an object. A manifestation relation can be added or removed from a released item or item revision.

– A form can have a manifestation relation to an item or item revision. – Only version 0 (zero) of a dataset can have a manifestation relation to an

(39)

– An item revision can have a manifestation relation to another item or item revision.

– An item revision cannot have a manifestation relation to another item revision if they are both revisions of the same item.

• Specification

The specification relation associates data which defines the item revision. Examples are CAD models for parts or word processor files for documents. Rules for this relation are as follows:

– An item revision must have write access to add or remove a specification relation to an object.

– A form can have a specification relation to an item or item revision. – Only version 0 (zero) of a dataset can have a specification relation to an

item or item revision.

– A folder, envelope, BOMView or BOMView Revision cannot have a

specification relation to an item or item revision.

– An item cannot have a specification relation to another item or item revision.

– An item revision can have a specification relation to another item or item revision.

– An item revision cannot have a specification relation to another item revision if they are both revisions of the same item.

• Reference

The reference relation associates any data to an item or item revision. Rules for this relation are as follows:

– An item or item revision does not need to have write access to add or remove a reference relation to an object. A reference relation can be added or removed from a released item or item revision.

– Any object can have a reference relation to an item or item revision. – Only version 0 (zero) of a dataset can have a reference relation to an item

or item revision.

– A reference object cannot reference itself.

• Revision

The revision relation associates item revisions to the appropriate item. Rules for this relation are as follows:

– An item must have write access to add or remove an item revision from the item.

(40)

– The revision relation in an item is established by creating a new revision of an item using the provided functionality. An item revision cannot be cut or pasted into an item.

• BOMView

The BOMView relation associates the product structure to an item. Rules for this relation are as follows:

– An item can only have one BOMView relation.

– A BOMView relation can represent the product structure of only one item.

• BOMView Revision

The BOMView Revision relation associates a product structure revision to an item revision. Rules for this relation are as followed:

– An item revision can only have one BOMView Revision relation.

– A BOMView Revision relation can represent the product structure of only one item revision.

Modifying an Item/Item Revision

Teamcenter is designed to organize the data created by other applications in a logical manner. When an item is first created, an item ID is reserved. It is only by adding data to an item, however, that the item becomes meaningful.

Datasets are used to store information created by other applications. These datasets can be associated to an item and item revision.

In Teamcenter, both item revision and dataset versions are intended to represent modifications to information. Item revisions represent the item at significant milestones. Dataset versions represent day to day changes. An item has revisions; a dataset has versions.

There are two ways to modify an item and item revision. One method is to simply add or remove relations from the item and item revision by using cut and paste. Another method is to modify the contents of an object that is currently related to the item and item revision.

Item Type

Types are used to specialize the behavior of Teamcenter objects. Datasets implement the most extensive use of type. The dataset type is used to categorize datasets. Examples of dataset types are a document, an NX part, and a spreadsheet. When a document dataset type is opened, the word processor application associated to this dataset type is opened. When an NX part dataset type is opened, the NX application associated to this dataset type is opened. For each dataset type, the available operations (for example print and open) are defined, as well as the specific behavior of each operation.

(41)

The system, as delivered, provides a generic item type called item. If you need additional types, they can be created by the system administrator at your site.

Dataset Model

Figure 4-3 shows the RevisionAnchor that creates a new logical dataset.

Figure 4-3. Dataset Model Unique ID Enforcement

The unique ID enforcement is performed at the application level. Each time the

New→Dataset command is used to create a dataset, the Save As and Import

commands are used, or the dataset is edited using the Properties command, the validation function is called to ensure the dataset ID (id) and revision (rev) combination is unique within that specified dataset type.

Also, for each dataset type, if the dataset ID is created using theAssign button, a separate counter generates the next unique id that is available for a standalone dataset. This counter ensures the id and rev is unique within the same dataset type.

Form Model

Forms provide the ability to store customer defined attributes. Teamcenter provides standard forms. Most of the forms used at a customer site, however, are modified to capture the information unique to its business.

Forms can be stored as POM objects. Attributes in the forms can be set and retrieved using Form ITK functions. Forms stored as POM objects can use the POM query ITK functions in addition to the Form ITK functions. When a form is stored as a POM object, the database schema must be updated to recognize the new POM object. Figure 4-4 show a diagram of the form model.

(42)

Figure 4-4. Form Model

System Administration Model

The POM_application_object class and all its subclasses have owners and protection which can be altered by the system administrator. Figure 4-5 shows a diagram of the system administration model.

(43)

Access Control Model

Access control list (ACL) entries consist of a reference to a group and/or a user and the access rights grant to such a subject. A subject is an object that can be granted access rights in Teamcenter. Figure 4-6 shows a diagram of the access control model.

Figure 4-6. Access Control Model

Application Encapsulation Model

The application encapsulation data model is designed to enable Teamcenter to maintain relations between data and the applications that can present it to the end user.

The model provides a means of declaring an application to Teamcenter by creating instances of the Tool class. It also provides a means of determining which tool to use for the creation and manipulation of various pieces of data. This is done by providing a DatasetType object class for you to use when specifying the tools that can create and manipulate data.

A tool can be a shell. A shell is an executable image written to execute other legacy images. The shell uses the ITK to extract data from Teamcenter and update Teamcenter with data created by the execution of legacy systems. A shell can be developed that manages all applications at a site that can be invoked and supplied input on the command line. This shell can present a form to the user to fill out before executing the legacy system so the shell can make any records that site may need for any other reasons.

A shell could also be developed to copy data from Teamcenter into a temporary or working directory from which a legacy (non-integrated) application is run. This allows some support for applications that always require interactive input. If the shell moves required files into the working directory, and the application reads files from the current directory if only file names are specified, it would be very difficult to put procedures in place that require the user to use only file names when using such applications. If this is done, a shell can prepare data for an application, record the state of the directory and use that information to determine what happened after the application is terminated. In this type of example, the input/output parameters of the application declaration in Teamcenter can allow this shell to ignore some scratch files that may be left in the directory by the executing application.

(44)

The Dataset class is the workspace object that an end user sees in their workspace. The shell or integrated application associates one or more other pieces of data to the dataset. More often than not, this means associating files for existing applications. Some applications require several files in order to run. When this is the case, a named reference can be created for each file. The name of the reference is often the extension of the file but does not have to be. A CAD system may have a file in which it stores geometric data with a .gmd extension, finite element modeling data in a file with a .fem extension, and drawing data in a file with a .drw extension.

For such a CAD system, you could find references named geometry, fem, and

drawing, or gmd/fem/drw as the shell chooses. If you use the extensions, users do

not have to change the reference names during import, since by default the import assumes the reference names correspond to the file extensions.

The model shows that the named reference can refer to an ImanFile object or other descendant class of the POM object. This means a shell can be implemented that does not use the ImanFile object to store file data, but instead uses its own file object to store such information. However, you should do this rarely since there is a loss of integrity that is provided by the ImanFile object. However, the flexibility it provides may be necessary in some cases.

The RevisionAnchor object is provided to support revisioning of datasets. Whenever a dataset is created, a RevisionAnchor object is also created. This object maintains a list of working revisions of the dataset. However, it is up to the shell/integrated tool to use this facility. To use it, you must make revision copies and then make changes to these copies.

(45)

Class Hierarchy

The information in this section describes the hierarchy of classes (taxonomy). Understanding this hierarchy, or returning to it, helps with understanding the rest of the Teamcenter model description, which shows relationships and gives a more detailed description of individual classes.

Class objects have a meaningful hierarchy that relates to the Teamcenter layered software architecture previously discussed. It is presented in an indented outline form.

The following legend defines the mnemonic descriptions given in parenthesis in figure 4-7.

AE Application Encapsulation

AOM Application Object Module

BOM Bill Of Materials

CR Cascade Release

EPM Enterprise Process Modeling

FL Folder Manager

FORM Forms

IMF Teamcenter Engineering File

ITEM Item

MAIL Teamcenter Engineering Mail POM Persistent Object Manager

PS Product Structure

SA System Administration

UOM Unit of Measure

VM Teamcenter Engineering Volumes

(46)

Figure 4-7 shows the more common classes in the hierarchy. For more information about other classes, see the Schema Editor.

(47)

Object-Oriented Data

An object is a data structure. It is basically the same as an entity or an instance of a class. A class defines a type of object, its attributes, and methods that operate on it. For example, folder is a class in Teamcenter. It is defined to have a name, a description, and a list of entries. These are the attributes of the folder class. When a folder is instantiated, an actual folder object is created. It has attributes as described here. There are also methods or functions defined for the folder class, such as Insert and Remove.

Attributes in Teamcenter can be integer, float, boolean, string, date, tag, or arrays of any of the above types.

The attributes in Teamcenter can have some of following characteristics:

Unique There can be no duplicate values of the attribute in all of the instances of the class.

Protected The attribute can only be modified by the application that_{created the object.} NULL Allowed If this characteristic is not true, then the object cannot be saved

until the attribute is set.

Upper Bound The highest value that the attribute can have. Lower Bound The lowest value that the attribute can have.

Inheritance

A subclass inherits both attributes and methods from superclasses.

Multiple inheritance means that a class has two superclasses. That is, it inherits the attributes and methods from two different classes. There are no instances of multiple inheritance in Teamcenter.

A superclass may be a generalization of many similar classes. For example, the

WorkspaceObject superclass is a generalization for all of the classes whose

instances may be seen in the workspace (for example, in a folder). All of the attributes and methods that are common to the Dataset, Folder, and other classes are defined once in the WorkspaceObject superclass, rather than being defined many times. Usually, generalizations are abstract or non-instantiable. This means that the class exists for conceptual or convenience reasons, but you cannot actually create an instance of one.

A subclass may be a specialization of another class. For example, the Envelope subclass is a specialization of the Folder class. In this case, a new class is being defined that is just like another one except for some additional attributes and/or some specialized behavior such as a specialized method.

(48)

Object-Oriented Language

An object-oriented language is a programming language that has built in key words or constructs that either force or facilitate object oriented programming. For example, C++ is one, because it supports classes, objects, inheritance, and polymorphism. The C language is not.

However, you can do object oriented programming with a non-object oriented language; it is just harder. You can certainly have an object model with inheritance of attributes and methods without using an object oriented language. This is what we present through ITK.

Internally, much of Teamcenter is written in C++. This provides an easy way of handling polymorphism. You can take advantage of this in the ITK as well. If you want to execute a method on an object, you do not need to call a function specific to that action-class pair. You may call any function with that action up the tree of superclasses for the selected object. For example, if you want to ask the name of an envelope, you do not need to call the EMAIL_ask_envelope_name function (in fact, that function does not exist). You can call the WSOM_ask_name function two levels up in the hierarchy instead. That function realizes that it was actually passed an envelope and invokes the envelope’s method to get the name.

(49)

Chapter

5 Using ITK Functions

Format . . . 5-1 Variable Naming Conventions . . . 5-3 Class Hierarchy . . . 5-3 Debugging . . . 5-4 Journal Files . . . 5-4 System Logs . . . 5-6 Logging . . . 5-6 Error Handling . . . 5-7 Teamcenter Errors . . . 5-7 Fixing Invalid Unicode Characters . . . 5-7 Memory Management . . . 5-10 Include Files . . . 5-10 Initializing Modules . . . 5-12 Special Data Types . . . 5-12 Compiling . . . 5-13 Linking Standalone Programs . . . 5-13 Important Comment for linkitk . . . 5-14 Linking User Exits in UNIX and Linux . . . 5-14 Linking User Exits in Windows . . . 5-15 Exporting New Symbols From libuser_exits.dll on Windows . . . 5-16 Compiling and Linking Server Exits in Windows . . . 5-17 Running the Executable . . . 5-20 Batch ITK . . . 5-21 Batch Program Template . . . 5-21 Compiling and Linking Batch Programs . . . 5-23 Supplier Custom Hooks . . . 5-24 Introduction . . . 5-24 Environment . . . 5-24 Building the Library File . . . 5-24

(50)

Registering User Exits Customization . . . 5-26 Registering Server Exits Customization . . . 5-28 Executing Multiple Customizations . . . 5-29 Registering Customizations . . . 5-30 CUSTOM_register_callbacks . . . 5-30 CUSTOM_register_exit . . . 5-30 CUSTOM_execute_callbacks . . . 5-31 CUSTOM_execute_callbacks_from_library . . . 5-32 Example . . . 5-33 Registering Runtime Properties Using Custom Hooks . . . 5-34

(51)

Chapter

5 Using ITK Functions

This chapter describes the format of ITK functions as well as details about writing, compiling, linking, and running ITK programs.

Format

All ITK functions have a standard format that attempts to give the most information possible in a small space. A template is shown below, followed by a more detailed description. All prototypes are located in include files named classname.h for the class of objects that the functions operate on. For more information about specific functions, see the Integration Toolkit Function Reference

The design intent for the format of ITK functions is to provide the maximum amount of information in a small space. The standard format is:

int module_verb_class_modifier ( const type variable-name[dimension] /* [I/O/OF] */ );

int Nearly all ITK functions return an integer error code. This code can be passed to the EMH_get_error_string function.

module This is the module designator. Related classes are grouped together in modules. For example, the Dataset,

DatasetType, Tool, and RevisionAnchor classes are all

handled by the AE module. Other examples of modules are

PSM, POM, FL, and MAIL.

verb This is the first key word describing an action to be taken on an object or set of objects. Common actions are create, add,

remove, copy, set, and ask.

class This is the class name or an abbreviation of the class name. The exceptions are for modules that only deal with one class, like Workspace or modules that deal with many classes, like WSOM and POM.

modifier This is a word or several words that give more description of how the action of the verb applies to the class. For example, in the RLM_update_af_status function, status indicates what is being updated in the af (authorization folder).

const Input pointer variables which are not meant to be modified

normally are declared with a const to ensure that they are not accidentally modified.

(52)

Chapter 5 Using ITK Functions

type This is the data type of the argument (for example, int,

tag_t*, or char***).

variable-name This is a variable name that is descriptive enough so a programmer does not need to look it up in the documentation.

dimension This value is normally specified for arrays where the calling program is responsible for allocating space. They are normally specified with a constant definition of the form module_description_c. These constants should be used in dimensioning arrays or looping through the values of an array to make your programs more maintainable. However, you may see the values of these constants in the include files. This is useful so you do not establish naming conventions that leads to name strings longer than can be passed to the functions.

I/O/OF These characters indicate whether the particular argument

is input, output or output-free. Output-free means that the function allocates space for the returned data and this space should be freed with the MEM_free function.

(53)

Using ITK Functions

Variable Naming Conventions

Variables in the interface are normally as descriptive as possible, consisting of key words separated by under-bars (_).

• Typedefs end in _t. • Constants end in _c. • Enums end in _e.

Most typedefs and constants begin with the module designator just like the function names to make it clear where they are meant to be used.

Class Hierarchy

Because Teamcenter is an object-oriented system, it is not necessary to have a function for every action on every class. Usually, functions associated with a particular class work with instances for any subclasses. For example, the FL_ functions for folders work with authorizations and envelopes. The AOM module and the WSOM module consist of functions that correspond to the methods of the

POM_application_object and WorkspaceObject abstract classes respectively. AOM functions work for all application objects and WSOM functions work for all

workspace objects.

When you create objects, an implicit lock is placed on the newly created object. After you perform an AOM_save, it is important that you call

AOM_unlock.

The same mechanism described here also enables standard Teamcenter functions to work on subclasses that you may define. For example, if you define a subclass of the

(54)

Debugging

This section contains information on ITK debugging aids such as journal files and log files.

Journal Files

Teamcenter optionally journals the calls to all of the ITK functions. This is in a file called journal_file after the program is run. This file can be very useful in finding out what your program has done and where it went wrong. There are 5 journaling flags in the system for the POM, PSM, RLM, SA, and CMMV modules and ITK in general. For POM, use the POM_set_env_info function; otherwise, use the xxx_set_journaling(int flag) function, where flag is equal to 0 (zero) for off or not equal to 0 for on. You could have ITK and RLM journaling on if you are working in that area and leave POM and PSM journaling off, ensuring that your journal file does not get cluttered with uninteresting information. Figure 5-1 shows how the POM logs input and output arguments. Input arguments are logged with their values, output arguments are logged on the way in with their names and on the way out with their values.

POM_start ( ’aali’, ’aali’, ’Information Manager’, user, topmost_class_id, pom_version) @* --> 6s @* FM_init_module @* --> 8s @* EIM_PM_id_of_process ( 103, process_id) @* process_id = 558 returns 0

@* returns 0 [in 2 secs] @* AM_init_module @* FM_init_module @* returns 0 @* FM_allocate_file_id ( file) @* returns 0, file = 000127cc08b2 @* --> 9s @* AM_identify_version ( identity) @* returns 0 @* returns 0 @* EIM_PM_id_of_process ( 105, process_id) @* process_id = 559 returns 0 @* --> 10s @* FM_read_file ( 00650002) @* returns 0 @* --> 11s @* FM_ask_path ( 00650002, 750, path)

@* returns 0, path = ’/home/demov2/user_data/d1/f000627cbd90f_pom_schema’ @* --> 12s @* FM_unload_file ( 00650002) @* returns 0 @* --> 14s @* FM_allocate_file_id ( file) @* returns 0, file = 000227cc08b2

@* user = 006500e0 <QAscMZ60AAAAyD>, topmost_class_id = 006500d0, pom_version = 100 returns 0 (in 16 secs)

(55)

Figure 5-2 shows another example of a journal file.

POM_name_of_class ( 00650021, class_name) @* class_name = ’Signoff’ returns 0

POM_class_id_of_class ( ’Signoff’, class_id) @* class_id = 00650021 returns 0

POM_describe_class ( 00650021, NULL, application_name, descriptor, n_attrs, attr_ids) @* application_name = ’Information Manager’, descriptor = 0, n_attrs = 4,

@* attr_ids = { 00650022, 00650023, 00650024, 00650025 } returns 0

POM_describe_attrs ( 00650021, 4, /

{ 00650022, 00650023, 00650024, 00650025 }, names, types, max_string_lengths, referenced_classes, lengths, descriptors, attr_failures)

@*

@* names = { ’comments’, ’decision’, ’group_member’, ’decision_date’ }, @* types = { 2008, 2005, 2009, 2002 },

@* max_string_lengths = { 240, 0, 0, 0 },

@* referenced_classes = { 00000000 <AAAAAAAAAAAAAA>, 00000000 <AAAAAAAAAAAAAA>, 00650054, 00000000 <AAAAAAAAAAAAAA> }, @* lengths = { 1, 1, 1, 1 }, @* descriptors = { 64, 0, 0, 64 }, @* attr_failures = { 0, 0, 0, 0 } returns 0 POM_free ( 0041ac28) @* returns 0

POM_subclasses_of_class ( 00650021, n_ids, subclass_ids) @* n_ids = 0, subclass_ids = {}

@* NULL array pointer, length 0 @* returns 0

Figure 5-2. Journal File Example 2

The first few hundred lines of a journal file contain a lot of text like the example above. This is the result of reading in the schema. If you define POM classes, you can see this information in there also. This is helpful in determining if you have in the database what you think you have in it. Also, when you see class IDs or attribute IDs elsewhere in the journal file, you can refer to this section to see what they are.

(56)

Figure 5-3 is an example of an application function being journaled.

RLM_ask_approver_roles ( 006500e1)

@* POM_length_of_attr ( 006500e1, 00650009, length) @* length = 1 returns 0

@* POM_ask_attr_tags ( 006500e1, 00650009, 0, 1, values, is_it_null, is_it_empty)

@* values = { 006500dc <AAlccPghAAAAyD> }, is_it_null = { FALSE }, @* POM_free ( 0041cf50)

@* returns 0

@* POM_free ( 0041d390) @* returns 0

@* role_count = 1, approver_roles = { 006500dc <AAlccPghAAAAyD> } returns 0

Figure 5-3. Journal File Example 3

The journal information for lower level routines are nested inside the higher level routines.

System Logs

In general, the system log is less useful, but sometimes you may see a

POM_internal_error or something else that does not make sense to you. You can

look in the system log to understand what went wrong. For example, if your program crashes you may not have an error message, but the end of the system log may show what the program was trying to do just before crashing.

Logging

For more information on logging, see the Log Manager (LM) module reference section in the Integration Toolkit Function Reference.

(57)

Error Handling

Teamcenter Errors

Teamcenter stores errors on a central error stack. An error may be posted at a low level and each layer of the code handles the error reported by the level below, potentially adding a new error of its own to the top of the stack to add more contextual information to the exception being reported. This stack of errors is what you see displayed in the Teamcenter error window in the user interface. ITK functions always return the top error from the stack if there is one. If the call is successful, ITK_ok is returned.

The Error Message Handler (EMH) ITK functions enable you to access the full error stack and decode individual Teamcenter error codes into the internationalized texts that are defined in the UIL code and displayed in the error windows at the user interface. EMH ITK functions are defined in the emh.h header file. They give the ability to store errors, access errors on the stack, and decode error codes into internationalized text. For additional information on EMH functions, see the EMH section in the Integration Toolkit Function Reference manual.

It is good practice to acknowledge that you have received and handled an error reported by an ITK call by clearing the error store with a call to the

EMH_clear_errors function. However, if you do not do this it normally

does not cause a problem, as all initial errors should start a new stack with a call to the EMH_store_initial_error function.

Fixing Invalid Unicode Characters

If an object attribute has an invalid Unicode character in it, the workspace object gives an invalid Unicode character error in the rich client’s DOS window for some operations, such as expanding a folder. It also may make a large number of network calls, which dramatically slows Teamcenter operations. To determine if this is the case, follow these steps:

1. Enable the rich client CORBA call profiler by adding the following line to the

client_specific.properties file:

corbaCallProfiler=start

2. Log in to Teamcenter.

3. Clear the Teamcenter Network Communications Profiler.

4. Perform a workspace object operation, such as expanding a folder.

5. Update the CORBA call profiler. You can see the icct calls for the workspace object operation.

(58)

If there are a larger number of network calls, check the rich client’s DOS window for an invalid Unicode character error for this operation. The error looks like this:

DefaultValidationEventHandler: [FATAL_ERROR]: An invalid XML character (Unicode: invalid-character) was found in the value of attribute "attribute" and element is "element".

If it is an invalid character error, open the gateway response in the Teamcenter Network Communication Profiler with a text editor. In figure 5-4, the 003104-Arch

Modeler Var Enh-Phase 2 item has an invalid character in its description

(Architecture Modeler Variability Enh Phase II):

</Struct> </Entry> <Entry>

</Entry> <Entry>

</Entry> <Entry>

</Struc> </Entry>