Teamcenter 10.

1
Server Customization Programmers
Guide

Publication Number
PLM00074 J

Proprietary and restricted rights notice

This software and related documentation are proprietary to Siemens Product

Lifecycle Management Software Inc.
2013 Siemens Product Lifecycle Management Software Inc. All Rights Reserved.
Siemens and the Siemens logo are registered trademarks of Siemens AG. Teamcenter
is a trademark or registered trademark of Siemens Product Lifecycle Management
Software Inc. or its subsidiaries in the United States and in other countries. All
other trademarks, registered trademarks, or service marks belong to their respective
holders.

Server Customization Programmers Guide

PLM00074 J

Contents

Proprietary and restricted rights notice . . . . . . . . . . . . . . . . . . . . . . . . .

Getting started with server customization . . . . . . . . . . . . . . . . . . . . . . . 1-1

Before you begin . . . . . . . . . . . . . . . . . . . . . . .
Methods for customizing the Teamcenter server
Siemens PLM Software customization support .
Basic server concepts . . . . . . . . . . . . . . . . . . .

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

1-1
1-2
1-2
1-3

Data-model-based customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Introduction to data-model-based customization . . . . . . . . . . . . . . . . . . . . . . 2-1
Working with the create operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Call Teamcenter C++ API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Teamcenter Services customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Introduction to Teamcenter Services customization . . . . . . . . . . . . . . . . . . . . 3-1
Enable Teamcenter Services customization . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Basic tasks for Teamcenter Services customization . . . . . . . . . . . . . . . . . . . . 3-2
ITK customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Introduction to the ITK . . . . . . . . . . . . . . . . .
Core functions . . . . . . . . . . . . . . . . . . . . . . .
Persistent Object Manager layer . . . . . . . . . .
Customize text and error messages . . . . . . . .
ITK customization for Teamcenter applications

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

4-1
4-29
4-33
4-70
4-72

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

Figures
Classes view (POM schema) . . . . . . . . . . . . . . . . . . . . . .
Business object view (logical representation of the schema)
Abbreviated view of the schema . . . . . . . . . . . . . . . . . . .
Inheritance of the WorkspaceObject class . . . . . . . . . . . .
Secondary business objects (pre-Teamcenter 8) . . . . . . . .
Primary business objects (post-Teamcenter 8) . . . . . . . . .
Properties tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Framework interfaces . . . . . . . . . . . . . . . . . . . . . . . . . .
Generated code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teamcenter interaction prior to Teamcenter 8 . . . . . . . . .

PLM00074 J

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

1-4
1-4
1-5
1-6
1-8
1-8
1-9
2-2
2-4
2-5

Server Customization Programmers Guide

Contents

Teamcenter interaction after Teamcenter 8 . . . .

Single API signature for the create operation . . .
Sample ITK project . . . . . . . . . . . . . . . . . . . . .
Add existing property sheet . . . . . . . . . . . . . . .
Environment dialog box . . . . . . . . . . . . . . . . . .
Property page . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Runtime Library . . . . . . . . . . . . . . . . .
Set break points . . . . . . . . . . . . . . . . . . . . . . .
Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class hierarchy . . . . . . . . . . . . . . . . . . . . . . . .
Simple join . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mechatronics Process Management object model
Climate control system . . . . . . . . . . . . . . . . . .
Functionality connections . . . . . . . . . . . . . . . .
Allocation persistent object model . . . . . . . . . . .
Allocation run-time object model . . . . . . . . . . .
BOM view class attributes and methods . . . . . .
BOM view revision class attributes and methods
Occurrence class attributes and methods . . . . . .
View type class attributes and methods . . . . . . .
Note type class attributes and methods . . . . . . .
Product structure model . . . . . . . . . . . . . . . . .
Export route . . . . . . . . . . . . . . . . . . . . . . . . . .
Import route . . . . . . . . . . . . . . . . . . . . . . . . . .
Task model . . . . . . . . . . . . . . . . . . . . . . . . . . .
EPM object model . . . . . . . . . . . . . . . . . . . . . .

Server Customization Programmers Guide

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 2-6
. 2-11
. 4-6
. 4-8
. 4-9
. 4-10
. 4-11
. 4-11
. 4-34
. 4-37
. 4-54
. 4-77
. 4-79
. 4-81
. 4-87
. 4-88
4-122
4-124
4-126
4-128
4-128
4-129
4-135
4-137
4-157
4-158

PLM00074 J

Chapter

Getting started with server

customization

Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Methods for customizing the Teamcenter server . . . . . . . . . . . . . . . . . . . . . . 1-2
Siemens PLM Software customization support . . . . . . . . . . . . . . . . . . . . . . . 1-2
Basic server concepts . . . . . . . . . . . . . . . . . . .
Teamcenter data model structure . . . . . . . .
Basic data model terms . . . . . . . . . . . .
Introduction to primary business objects
Introduction to properties . . . . . . . . . .
Libraries . . . . . . . . . . . . . . . . . . . . . . . . .
Install sample files . . . . . . . . . . . . . . . . . .
Writing warnings or errors to logs . . . . . . .

PLM00074 J

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

1-3
1-3
1-7
1-7
1-8
1-10
1-11
1-11

Server Customization Programmers Guide

Chapter

Getting started with server

customization

Before you begin

Prerequisites

The following are required for both data-model-based framework

customization and Integration Toolkit (ITK) customization:

A tool to write code

o

For data model and services customization, use the

Business Modeler IDE.
For more information, see the Business Modeler IDE
Guide.

For ITK customization, use the C++ integrated

development environment (IDE) of your choice.

A compiler for compiling code

Use a C++ compiler for all server-side customizations
(ITK, services, and data-model-based customization).
For supported versions, see the Siemens PLM Software
Certification Database at the following URL:
http://support.industrysoftware.automation.siemens.com/
certification/teamcenter.shtml
When using Windows, use Visual Studio 2010 Service Pack
1. If compiling on a 64-bit Windows machine, you must
install the x64 Compilers and Tools option to the Visual
Studio compiler.

A test installation of a Teamcenter server and clients (rich

client and thin client) to test custom code
For Teamcenter installation instructions, see the server
installation manuals, the Installation on Windows Servers
Guide and the Installation on UNIX and Linux Servers
Guide. For client installation instructions, see Installation
on Windows Clients Guide and the Installation on Linux
Clients Guide.

PLM00074 J

Server Customization Programmers Guide

1-1

Getting started with server customization

Chapter 1

Enable server
customization

To enable data-model-based customization or services

customization, install the Business Modeler IDE.
For more information, see Enable data-model-based
customization.

Configure server To configure data-model-based customization or services

customization
customization, set up the coding environment in the Business
Modeler IDE.
For more information, see the Business Modeler IDE Guide.

Methods for customizing the Teamcenter server

You can customize the Teamcenter server using the following methods:

Business Modeler IDE

An integrated development environment (IDE) tool that allows you to customize
the server using business object and property operations, extensions, and user
exits.
For more information, see Introduction to data-model-based customization.

Teamcenter Services
A server-side customization method that uses standard service-oriented
architecture (SOA) to provide the framework.
For more information, see Introduction to Teamcenter Services customization.

Integration Toolkit (ITK)

An older, server-side customization method.
For more information, see Introduction to the ITK.

For instructions about how to perform client-side customizations, see the Client
Customization Programmers Guide.

Siemens PLM Software customization support

Siemens PLM Software 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.
As Teamcenter evolves and advances, leveraging newly available technologies,
Teamcenter will make the ability to extend and tailor Teamcenter as flexible and
simple as possible. The direction is to fully leverage the developing Eclipse paradigm
to consolidate the thin client and rich client frameworks. A single client framework
allows extending both the thin client and rich client with a single extension. Note

1-2

Server Customization Programmers Guide

PLM00074 J

Getting started with server customization

that this consolidation will change the current extension model for the thin client
in the future.
Siemens PLM Software 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 Siemens PLM Software 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. Siemens PLM Software
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 Siemens PLM Software customer support representatives at GTAC for further
assistance.

Basic server concepts

Before beginning server customization, familiarize yourself with some basic concepts
about Teamcenter server processing.

Teamcenter data model structure

Before performing customizations, it is important to understand the Teamcenter
data model structure. The Teamcenter data model is the collection of all data
modeling objects that represent real-world objects.
The Teamcenter persistent object manager (POM) defines the architecture (schema)
using classes and business objects:

Classes
The persistent representations of the schema. Classes can be seen in the Classes
view of the Advanced perspective in the Business Modeler IDE.

Business objects
The logical representations of the classes, also known as types. Business objects
can be seen in the Business Objects view of the Advanced perspective in the
Business Modeler IDE.
Each class is mapped to a primary business object whose name is the same as the
class name.

PLM00074 J

Server Customization Programmers Guide

1-3

Chapter 1

Getting started with server customization

Classes view (POM schema)

Business object view (logical representation of the schema)

Business objects represent the different kinds of objects you want to manage, such as
items, datasets, forms, folders, and so on. The following figure shows an abbreviated
view of the schema showing these objects.

1-4

Server Customization Programmers Guide

PLM00074 J

Getting started with server customization

POM_object
POM_application_object
WorkspaceObject
Dataset
Folder
Form
Item
ItemRevision

Abbreviated view of the schema

To see the information on a class or business object, right-click it in the Classes
view or the Business Objects view and choose Open in UML Editor. To see the
inheritance relationships the object has to other objects, right-click the object in the
UML Editor and choose ShowInheritance to Root. For example, the following
figure shows the inheritance of the WorkspaceObject class.

PLM00074 J

Server Customization Programmers Guide

1-5

Chapter 1

Getting started with server customization

Inheritance of the WorkspaceObject class

For more information about how to work with the UML Editor, see the Business
Modeler IDE Guide.

1-6

Server Customization Programmers Guide

PLM00074 J

Getting started with server customization

Basic data model terms

Term

Definition

Class

A class is the definition of an object implemented in the

Teamcenter data model. A class has a set of attributes,
some of which are inherited from parent classes and
some of which are defined directly for the class.

Business object

A business object is the specialization of a Teamcenter

class based on properties and behavior.

Primary business object

A primary business object corresponds to each POM

class (that is, the primary business object name
is the same as the POM class name). Teamcenter
automatically creates the primary business object when
a new POM class is instantiated.

Secondary business
object

Secondary business objects are all business objects that

belong to the same POM class. Secondary business
objects inherit all the properties and behavior of the
primary business object.

Attribute

An attribute is a persistent piece of information that

characterizes all objects in the same class.

Property

A property is a piece of information that characterizes

all instances of the same business object. At a minimum,
all sub-business objects have properties that correspond
to the attributes for the associated class. Properties
can also represent other types of information such as
relationships and run-time data.

Introduction to primary business objects

A primary business object corresponds to each POM class, and the primary business
object name is the same as the POM class name. The primary business object uses
its corresponding POM class to store its data. (Teamcenter automatically creates the
primary business object when a new POM class is instantiated.)
However, a secondary business object uses its parent POM class as its storage class
(see the following figure). Prior to Teamcenter 8, each POM class mapped to multiple
business objects, and all business objects were secondary. In this scenario:

PLM00074 J

Custom properties were added to a master form.

ITK extensions in prevalidation, postvalidation, and validation actions and user

exits were the only way to extend functionality.

C++ classes were available only to Siemens PLM Software developers and were
not exposed. C++ classes mapped to one POM schema class and implemented
the behavior for the primary business objects. Business logic for custom business
objects (for example, MyItem) was added into the parent C++ class, or was
written into separate ITK functions outside the C++ class hierarchy.

Server Customization Programmers Guide

1-7

Getting started with server customization

Chapter 1

Secondary business objects (pre-Teamcenter 8)

After Teamcenter 8, the business object hierarchy is primarily one-to-one with the
POM schema class hierarchy. In this scenario:

Properties can be added directly to the custom business objects.

There are still ITK extensions used for prevalidation, postvalidation, and
validation actions.

C++ operations are available to everyone. The C++ class hierarchy is one-to-one
with the business object hierarchy.

You can create new operations and services. You can put the business logic for
custom business objects in the C++ class (for example, MyItem) and use the
inheritance model to add onto the parent behavior or override custom behavior.

You can continue to use the master form to support legacy customizations or improve
loading performance when using large amount of properties.

Primary business objects (post-Teamcenter 8)

Note

Secondary business objects can be converted to primary business objects

using the Business Modeler IDE by right-clicking the secondary business
object in the Business Objects view of the Advanced perspective and
choosing Convert to primary.
For more information, see the Business Modeler IDE Guide.

Introduction to properties
A property is a piece of information that characterizes all instances of the same
business object. To see all the properties on a business object, open the business

1-8

Server Customization Programmers Guide

PLM00074 J

Getting started with server customization

object from the Business Objects view in the Advanced perspective in the Business
Modeler IDE and click the Properties tab.

Properties tab
Properties contain information such as name, number, description, and so on. A
business object derives its persistent properties from the attributes on its persistent
storage class. Business objects can also have additional properties such as run-time
properties, compound properties, and relation properties.
You can add the following kinds of properties:

Persistent
Persistent properties are properties of business objects that remain constant
on the object.

Run-time
Run-time properties are derived each time the property is displayed. Their data
is derived from one or more pieces of system information (for example, date or
time) that are not stored in the Teamcenter database.

Compound
Compound properties are properties on business objects that can be displayed as
properties of an object (the display object) although they are defined and reside
on a different object (the source object).

Relation
Relation properties are properties that define the relationship between objects.
For example, a dataset can be attached to an item revision with a specification,
requirement, or reference relation, among many others.

After you add a property, you can change characteristics of the property by using
property constants. For example, by default, when you add a persistent property
is it read only. To make it writeable, you must change the Modifiable constant
on the property from Read to Write.
For more information, see the Business Modeler IDE Guide.

PLM00074 J

Server Customization Programmers Guide

1-9

Getting started with server customization

Chapter 1

Libraries
A library is a collection of files that includes programs, helper code, and data. Keep
the following in mind when working with libraries:

Create a library in the Advanced perspective of the Business Modeler IDE

by opening the Code GenerationLibraries folders in the Extensions view,
right-clicking the Libraries folder, and choosing New Library.

After you write your C++ code, choose ProjectBuild Project in the Business
Modeler IDE to build the libraries containing server code.

If you have codeful customizations, you cannot deploy from the Business
Modeler IDE for testing because codeful customizations have libraries.
Instead, you must package your template so that libraries are placed into a
template-name_rtserver.zip file, and then install the packaged template using
Teamcenter Environment Manager (TEM).

Ensure that libraries are placed in the correct directories:

o

Ensure that by default the TC_LIBRARY environment variable is set to

TC_ROOT\lib on all platforms.

Place libraries for user exits, server exits, and custom exits (supplier custom
hooks) in the directory specified by the TC_USER_LIB environment
variable (preferred), the TC_BIN environment variable (for Windows), or
the TC_LIBRARY environment variable (for UNIX).

Place libraries for legacy operations in any directory as long as it is listed in

the BMF_CUSTOM_IMPLEMENTOR_PATH preference.

Place libraries for the C++ operations in the directory specified by the
TC_USER_LIB environment variable (preferred) or the TC_LIBRARY
environment variable (Windows and UNIX).

Note

For ITK, as of Teamcenter 8.1, the mem.h header file moved from the
libitk library to the libbase_utils library. The mem.h header file contains
low-level methods related to memory allocation and release. These methods
were exported from the libitk library and had circular dependencies with
some application libraries that affected delay loading of libraries. To address
this issue, a new low-level libbase_utils library is introduced. The functions
in the mem.h file are now exported from this new library.
The old header mem.h file still exists and includes the new
base_utils/Mem.h header. Existing customization code should compile
without any changes. However, as the functions are now exported from the
libbase_utils library, the existing link dependency on the libitk library
does not work.
For any custom code using functions from the mem.h file, link dependency
on the libbase_utils library must be added. For code where usage of the
libitk library is limited to only functions from the mem.h file, the existing
dependency on the libitk library can be removed in its entirety.

1-10

Server Customization Programmers Guide

PLM00074 J

Getting started with server customization

Install sample files

Sample files are provided to help you learn how to leverage Teamcenter technologies
and extension points. Siemens PLM Software provides guidance in the samples
that is both useful and aligned to best practices, but samples are provided on an
unsupported basis.
Caution

Use samples at your own risk. Samples are subject to removal or change
between releases.

1. Start Teamcenter Environment Manager (TEM).

2. In the Maintenance panel, select Configuration Manager and click Next.
3. In the Configuration Maintenance panel, select Perform maintenance on an
existing configuration and click Next.
4. In the Configuration panel, select the configuration from which the corporate
server was installed. Click Next.
5. In the Feature Maintenance panel, under the Teamcenter section, select
Add/Remove Features. Click Next.
6. In the Features panel, under Server Enhancements, select Sample Files.
7. Click Next.
8. In the Confirm Selections panel, click Next.
The sample files are placed at the following location:
server-install-location\sample

Writing warnings or errors to logs

Use the TC_write_syslog API to write warnings to the syslog, and use the
TC_report_serious_error API to write errors to the syslog. To use these functions,
include the tc.h file.

TC_write_syslog API
Use this function to write warnings or information level statements to the
Teamcenter syslog file, for example:
extern TC_API void TC_write_syslog (
const char*
control_string,
...
);

/**< (I) */
/**< (I) */

Depending on the control_string string, the function may expect a sequence of

additional arguments, each containing one value to be inserted for each %-tag
specified in the control_string parameter, if any. There should be the same
number of these arguments as the number of %-tag that expect a value.

PLM00074 J

Server Customization Programmers Guide

1-11

Getting started with server customization

Chapter 1

Parameters

Description

control_string

Message to be written to syslog file. It

can contain embedded format tags that
are substituted by the values specified
in subsequent arguments and formatted
as requested. The number of arguments
following the control_string parameters
should be at least as much as the number of
format tags.

TC_report_serious_error API
Use this function to write error messages to Teamcenter syslog file, for example:
extern TC_API void TC_report_serious_error (
const char*
file_name,
/**<
int
line_number,
/**<
const char*
control_string,
/**<
...
/**<
);

(I)
(I)
(I)
(I)

*/
*/
*/
*/

Parameters

Description

file_name

The name of the file in which the error

occurred.

line_number

The line number at which the error occurred

control_string

Message to be written to the syslog file.

It can contain embedded format tags that
are substituted by the values specified
in subsequent arguments and formatted
as requested. The number of arguments
following the control_string parameters
should be at least as much as the number of
format tags.

Depending on the control_string string, the function may expect a sequence of

additional arguments, each containing one value to be inserted for each %-tag
specified in the control_string parameter, if any. There should be the same
number of these arguments as the number of %-tag that expect a value.

1-12

Server Customization Programmers Guide

PLM00074 J

Chapter

Data-model-based customization

Introduction to data-model-based customization . . . . . . . .

Basic concepts for data-model-based customization . . .
Data model customization framework . . . . . . . . . .
Data model customization framework paradigm . . .
Data model customization framework tier structure
Server interaction with the framework . . . . . . . . .
Basic tasks for data-model-based customization . . . . . .
Enable data-model-based customization . . . . . . . .
Subclass and extend operations . . . . . . . . . . . . . .
Perform C++ coding . . . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

2-1
2-1
2-1
2-2
2-3
2-4
2-6
2-6
2-7
2-8

Working with the create operation . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Single API signature for the create operation . . . . . . . . . . . . . . . . .
Calling generic creation C++ API at the server side . . . . . . . . . .
Calling generic creation ITK API at the server side . . . . . . . . . .
Calling generic creation Teamcenter Services API from the client
The create operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Implement the create operation on a new business object . . . . . . . . .

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

2-10
2-10
2-11
2-12
2-13
2-13
2-15

Call Teamcenter C++ API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16

PLM00074 J

Server Customization Programmers Guide

Chapter

Data-model-based customization

Introduction to data-model-based customization

Data-model-based customization means making changes directly to data model
objects, such as business objects. The Teamcenter data model framework supports
a single, coherent mechanism for developing new functionality in C++ by defining
business logic on business objects in the Impl class. This exposes the business logic
API in an object-oriented way. Coding customization typically involves adding a
new operation to a business object or overriding an implementation of an existing
operation on a business object. Use the Business Modeler IDE to perform this work.
Operations are Teamcenter functions, such as create, checkin, checkout, and so on.
Operations can be placed on custom business objects and properties. Operations on
a business object provide the interfaces for business logic. The implementation of
the business logic is done by functions or methods on the implementation class
corresponding to the business object.
For complete instructions about how to use the Business Modeler IDE to perform
server customizations, see the Business Modeler IDE Guide.

Basic concepts for data-model-based customization

Before performing data model customizations, you should be aware of some
basic concepts, including the customization framework. For example, you should
understand how the Impl class is implemented by the Dispatch class under the
BusinessObject interface.
Data model customization framework
The data-model-based customization framework supports a single coherent
mechanism for developing new functionality using C++. The framework:

Defines business logic on business objects in the Impl class of the business object.

Provides a consistent approach that can be used for internal Siemens PLM
Software development as well as for external customizations.

Is scalable (delayed loading of DLLs).

Exposes the business logic API in an object-oriented way (through interfaces).

Improves memory performance.

Using the Business Modeler IDE, you can autogenerate the C++ plumbing code
required to implement the business logic. This:

PLM00074 J

Server Customization Programmers Guide

2-1

Data-model-based customization

Chapter 2

Reduces implementation time.

Increases productivity because you can spend more time in writing business logic.

Enforces coding standards.

Aids future enhancements.

Data model customization framework paradigm

The data model customization framework has the following paradigm.

BusinessObject interface that defines the API for the business object. All
callers work only with the interface.

Dispatch class that implements the interface. It provides the overriding and
extensibility capabilities.

An abstract generated implementation class. This class provides getters and

setters for the attributes on the business object and any other helper methods
needed by the implementation.

Impl class that is the actual implementation where the business logic is
manually implemented by the developer.

Delegate class that delegates invocations to the implementation class and breaks
the direct dependency between the dispatch and implementation classes.

Framework interfaces

2-2

Class

Autogenerated Purpose

Interface

Yes

Server Customization Programmers Guide

C++ interface class. Defines

published/unpublished API. All server
caller code dependent on this business object
works with only this interface.

PLM00074 J

Data-model-based customization

Class

Autogenerated Purpose

Dispatch

Yes

Implements the interface. Provides the

overriding and extensibility (pre/post)
capabilities to the business object.

Generated
Implementation
(GenImpl)

Yes

C++ abstract Class. This class provides

methods to get/set attribute values in the
database and any other helper methods
needed by the implementation.

Implementation
(Impl)

No

Implementation class. The developer

implements the core business logic for the
business object in this class.

Delegate

Yes

C++ abstract class. This class breaks the

direct dependency between the dispatch and
implementation classes.

Note

Code is autogenerated in the Business Modeler IDE by opening the

Advanced perspective, right-clicking your project folder in the Business
Objects view, and choosing Generate CodeC++ classes.
For more information, see the Business Modeler IDE Guide.

Data model customization framework tier structure

In data model framework customization, most of the code pieces are autogenerated,
while you only need to write code in the implementation (Impl) file, as shown
in the following figure.
First you create the business objects and operations, and their definitions are
deployed to the database without writing any code. Then you generate code, creating
boilerplate files that provide inheritance and overriding behavior to the business
object. Finally, you write the custom logic for the operation in the stub provided in
the Impl file.

PLM00074 J

Server Customization Programmers Guide

2-3

Chapter 2

Data-model-based customization

Generated code
Server interaction with the framework
The data model customization framework supports a single coherent mechanism for
developing new business functionality by defining business logic on business objects.
Prior to Teamcenter 8, customizers wrote business logic everywhere: the rich client,
ITK, C++, services, and so on, as shown in the following figure. This was not a good
practice. By having business logic in the rich client, other clients did not get that
business logic, and by having business logic in ITK, customizers did not get override
capability and extensibility (pre-conditions, pre-actions, and post-actions). Having
this inconsistency in the location made business logic difficult to maintain, and some
business logic could get executed only in certain paths.

2-4

Server Customization Programmers Guide

PLM00074 J

Data-model-based customization

Teamcenter interaction prior to Teamcenter 8

The framework provides the solution to this problem. It isolates business logic in one
location: the Impl class, as shown in the following figure.
The business object interface provides a C++ API that the rich client and thin
client can interact with directly. Teamcenter Services and Integration Toolkit
(ITK) interfaces provide an additional layer of interaction, and remote clients
typically use these interfaces to interact with the server. The rich client typically
invokes Teamcenter Services interfaces, and the thin client interacts through the
ITK interfaces. (All access and modification of data in the database is done by the
business object interface.)

PLM00074 J

Server Customization Programmers Guide

2-5

Chapter 2

Data-model-based customization

Teamcenter interaction after Teamcenter 8

Basic tasks for data-model-based customization

To perform basic server customization tasks, use the Business Modeler IDE to create
operations and write implementation code.
For complete instructions, see the Business Modeler IDE Guide.
Enable data-model-based customization
To enable server customization, configure the Business Modeler IDE to generate
C++ boilerplate code and write implementation code.
For complete instructions, see the Business Modeler IDE Guide.
1. Install the Business Modeler IDE.
In the Solutions panel of the Teamcenter Environment Manager (TEM), select
Business Modeler IDE.

2-6

Server Customization Programmers Guide

PLM00074 J

Data-model-based customization

2. Create a project in the Business Modeler IDE.

Choose FileNewProject, and in the New Project dialog box, choose Business
Modeler IDENew Business Modeler IDE Template Project.
As you work through the wizard, ensure that you fill in the Code Generation
Information dialog box and the Build Configuration Information dialog box.
3. Set up the coding environment in the Advanced perspective of the Business
Modeler IDE.
Create the following objects:

Release
In the Extensions view, choose Code GenerationReleases, right-click the
Releases folder and choose New Release.

Library
In the Extensions view, choose Code GenerationLibraries, right-click the
Releases folder and choose New Library.

External data types (if needed)

In the Extensions view, open the Code GenerationData Types folder, and
right-click the External Data Type folder and choose New External Data Type.

After the environment is set up, you are ready to create C++ customizations.
Subclass and extend operations
The focus of server customization is defining business logic on business objects. To
perform this kind of customization, you must use the Business Modeler IDE to create
custom business objects and then place operations on those business objects.
For complete instructions, see the Business Modeler IDE Guide
1. Access the Advanced perspective by choosing WindowOpen
PerspectiveOtherAdvanced.
2. Create a custom business object.
In the Business Objects view, right-click the business object you want to extend
(for example, Item) and choose New Business Object.
3. Create an operation on a custom business object or property, or override an
operation.
In the Business Objects view, right-click the custom business object, choose
Open, and in the resulting editor, click the Operations tab.
Perform any of the following:

PLM00074 J

To add a business object operation, click the Operations folder and click
the Add button.

To add a property operation, click a custom property in the Property

Operations folder and click the Add button.

Server Customization Programmers Guide

2-7

Chapter 2

Data-model-based customization

To override an operation, click the operation you want to override in the

Operations or the Property Operations folder, and click the Override button.
(The Override button is available if the operation is inherited from a parent
business object, is marked that it can be overridden, and is not already
overridden.)

4. Save the new business object and the operation changes.

Choose FileSave Data Model, or click the Save Data Model button on the
main toolbar.
5. Generate code.
In the Business Objects view, right-click your project folder and choose
Generate CodeC++ classes.
6. Write an implementation in the generated business_objectImpl.cxx file.
Right-click in the Navigator view and choose Refresh. Add your implementation
at the bottom of the Source Folder\library\business_objectImpl.cxx file where
it contains the following text:
** Your Implementation **

For more information, see Perform C++ coding.

7. Build the libraries containing server code.
Choose ProjectBuild Project.
8. Package your template.
Choose FileNewOther, and in the New dialog box, choose Business Modeler
IDEPackage Template Extensions. This packages your changes into a
template that can be installed to a test server.
Note

You cannot use live update to distribute codeful customizations to a

server. The Business Modeler IDE packages the built C++ library as part
of its template packaging. The complete solution that includes the data
model and the C++ run-time libraries are packaged together.

9. Install the template to a test server to verify the new functionality.

After packaging, copy the resulting files from your project\output\packaging
directory to a directory on the test server where you want to install the template.
Using the Teamcenter Environment Manager (TEM), in the Features panel,
click the Browse button on the lower right side of the panel to browse to the
directory where you have copied the template files.
Perform C++ coding
Perform C++ coding in the C/C++ perspective in the Business Modeler IDE.
For complete instructions, see the Business Modeler IDE Guide.
1. Access the Advanced perspective by choosing WindowOpen
PerspectiveOtherAdvanced.

2-8

Server Customization Programmers Guide

PLM00074 J

Data-model-based customization

2. After writing a new operation or overriding an operation, generate the

boilerplate code.
In the Business Objects view, right-click your project folder and choose
Generate CodeC++ classes.
3. Switch to the C/C++ perspective
Choose WindowOpen PerspectiveOtherC/C++.
4. Open the code file.
Right-click the Source Folder\library\business_objectImpl.cxx file in the
Navigator view and select Open or Open With.
The file opens in an editor.
5. Write the implementation.
Add your implementation at the bottom of the business_objectImpl.cxx file
where it contains the following text:
** Your Implementation **

The implementation you write depends on what you want to accomplish:

Create a new operation

For example, you add an operation named myOperation to the MyObject
business object. The business logic for the myOperation operation needs to
be implemented in the MyObjectImpl::myOperationBase method:
/**
* This is a test operation.
* @param testParam Test Parameter
* @return Status. 0 if successful
*/
int MyObjectImpl::myOperationBase( int testParam )
{
// Your Implementation
}

Override an operation
For example, you override the myOperation operation in the MySubObject
business object. The business logic for the override needs to be implemented
in the MySubObjectImpl::myOperationBase method. It needs to call
MySubObjectGenImpl::super_myOperationBase to invoke the parent
implementation:
/**
* This is a test operation.
* @param testParam Test Parameter
* @return Status. 0 if successful
*/
int MySubObjectImpl::myOperationBase( int testParam )
{
// Your Implementation

// Invoke super implementation

stat = MySubObjectGenImpl::super_myOperationBase( int testParam );

PLM00074 J

Server Customization Programmers Guide

2-9

Data-model-based customization

Chapter 2

// Your Implementation
}

Note

You should not call MyObjectImpl::myOperationBase for

invoking parent implementation.

Call another operation

For example, you want to call the myOperation2 operation from the
myOperationBase method. The myOperationBase method should invoke
the myOperation2 operation on itself:
/**
* This is a test operation.
* @param testParam Test Parameter
* @return Status. 0 if successful
*/
int MyObjectImpl::myOperationBase( int testParam )
{
// Your Implementation

// Invoke another operation

// Generate in MyObjectGenImpl
myOperation2( int testParam );
// Your Implementation
}

The myOperation2 operation is auto-generated in the MyObjectGenImpl

implementation.
Note

You should not call MyObjectImpl::myOperation2Base.

Working with the create operation

The data model customization framework provides a single API (CreateInput) for
business object creation.

Single API signature for the create operation

The data model customization framework uses a single C++ API for creating
any business object: CreateInput. It works with the creInput object to hold
name/value pairs that are used for the business object creation.
The single API structure:

2-10

Enables each business object to have its own set of attributes that can be passed
into the create operation.

Allows a business object to override the parent create operation to add additional
validations or to handle additional processing.

Server Customization Programmers Guide

PLM00074 J

Data-model-based customization

Handles additional properties added to a COTS business object by an industry

vertical solution or a customer.

Handles sub-business objects in a codeless manner (no code generation and

writing code) when they are added by the core model, an industry vertical
solution, or a customer.

The metadata for the CreateInput API is different for different business objects
and is configured on the Operation Descriptor tab for the business object in the
Business Modeler IDE. This metadata is inherited and can be overridden down the
business object hierarchy. You can add additional attributes, and clients can query
this metadata to provide the appropriate create user interface.
For more information about the Operation Descriptor tab, see the Business Modeler
IDE Guide.

Single API signature for the create operation

Calling generic creation C++ API at the server side
To call the generic creation CreateInput C++ API at the server side, follow these
steps:
1. Construct a CreateInput object.

PLM00074 J

Server Customization Programmers Guide

2-11

Chapter 2

Data-model-based customization

2. Populate the CreateInput object with the input data, using generic property set
(C++) APIs.
3. Construct CreateInput objects for compounded objects and populate and assign
them to the CreateInput object of the primary object.
4. Call generic creation by passing in the CreateInput object.
5. Save the primary object.
6. Delete all the CreateInput objects.
The resulting code might appear similar to the following sample:
Int MyBoImpl::myOpBase( )
{
//your implementation
//Calling Generic Creation (C++)
Teamcenter::CreateInput* pItemCreInput = dynamic_cast<Teamcenter::CreateInput*>
(Teamcenter::BusinessObjectRegistry::instance().createInputObject
(Item, OPERATIONINPUT_CREATE));
pItemCreInput->setString("item_id", item_id, false);
Teamcenter::CreateInput* pRevisionCreInput = dynamic_cast<Teamcenter::CreateInput*>
(Teamcenter::BusinessObjectRegistry::instance().createInputObject(ItemRevision,
OPERATIONINPUT_CREATE));
pRevisionCreInput->setString("item_revision_id", rev_id, false);
tag_t item_rev_createinput_tag = ((Teamcenter::BusinessObject*)pRevisionCreInput)->getTag();
pItemCreInput->setTag("revision", item_rev_createinput_tag, false);
pItem = dynamic_cast<Teamcenter::Item *>(Teamcenter::BusinessObjectRegistry::instance().
createBusinessObject(pItemCreInput));
}

Calling generic creation ITK API at the server side

The following example is for the thin client because the
TCTYPE_set_create_display_value function is intended only for the thin client
tcscript implementation.
1. Construct a CreateInput object.
2. Populate the CreateInput object with the input data, using generic property
set (ITK) APIs.
3. Construct CreateInput objects for compounded objects and populate and assign
them to the CreateInput object of the primary object.
4. Call generic creation by passing in the CreateInput object.
5. Save the primary object.
6. Delete all the CreateInput objects.
The resulting code might appear similar to the following example:
Int MyFunction( )
{
//your implementation
//Calling Generic Creation (ITK)
TCTYPE_construct_create_input ( itemType, createInputTag );
TCTYPE_set_create_display_value( createInputTag, "item_id", 1, {"20080530"} );
TCTYPE_construct_create_input ( itemRevType, irCreateInputTag );

2-12

Server Customization Programmers Guide

PLM00074 J

Data-model-based customization

AOM_tag_to_string( irCreateInputTag, &tempUID );

strcpy( irCreateInputTagUid[0], tempUID );
TCTYPE_set_create_display_value( irCreateInputTag, "item_revision_id", 1, {A"} );
TCTYPE_set_create_display_value( createInputTag, "revision", 1, irCreateInputTagUid );
TCTYPE_create_object ( createInputTag, boTag );
AOM_save ( boTag );
}

Note

Whereas the TCTYPE_create_object ITK function is used to create

a single object, the TCTYPE_create_objects ITK function is used for
bulk creation of all the associated objects when you create an object with
associated objects, such as an item business object.

Calling generic creation Teamcenter Services API from the client

1. Construct a CreateInput object and populate the input into the appropriate
property value map.
2. Construct a CreateInput object for the compounded objects and populate and
assign them into the compound object map.
3. Make a single services invocation to create the business object.
The resulting code may appear similar to the following example:
CreateIn createIn = new CreateIn();
createIn.data.boName = "Item";
createIn.data.stringProps.put("item_id", "Item001);
CreateInput revCreateIn = new CreateInput();
revCreateIn.boName = "ItemRevision";
revCreateIn.stringProps.put("item_revision_id","ItemRevSOATest");
CreateInput itemMasterCreateIn = new CreateInput();
itemMasterCreateIn.boName = "Item Master";
itemMasterCreateIn.stringProps.put("project_id", "ItemProjectID");
CreateInput itemRevMasterCreateIn = new CreateInput();
itemRevMasterCreateIn.boName = "ItemRevision Master";
itemRevMasterCreateIn.stringProps.put("project_id", "ItemRevProjID");
revCreateIn.compoundCreateInput.put("IMAN_master_form_rev", new CreateInput[]
{itemRevMasterCreateIn});
createIn.data.compoundCreateInput.put("revision", new CreateInput[]{revCreateIn});
createIn.data.compoundCreateInput.put("IMAN_master_form", new CreateInput[]
{itemMasterCreateIn});
// Call the createObjects operation
CreateResponse resp = dataMgtService.createObjects(new CreateIn[]{createIn});

Note

Whereas the createObjects service operation is used to create a single

object, the bulkCreateObjects service operation is used for bulk creation of
all the associated objects when you create an object with associated objects,
such as an item business object.

The create operation

The create operation is an interface operation. You can view this operation and its
child operations in the Business Modeler IDE on the Operation tab for all business
objects.

PLM00074 J

Server Customization Programmers Guide

2-13

Data-model-based customization

Chapter 2

The create operation in turn calls a protected method, createBase, that is

implemented as an orchestration method and is not overridable, as shown in the
following example:
int POM_objectImpl::createBase( Teamcenter::CreateInput * creInput )
{
try
{
ResultStatus stat;
stat = finalizeCreateInput(creInput);
stat = validateCreateInput(creInput);
stat = createInstance(creInput);
stat = setPropertiesFromCreateInput(creInput);
stat = createPost(creInput);
}
}

The child operations that are marked in bold in the example can be overridden at
a child business object:

finalizeCreateInput operation
Override this operation to implement any special business logic code for handling
computed properties. Use it to:
o

Compute property values if not defined.

Assign a computed value to the CreateInput object using generic get/set

APIs.

For example, the item_id value is computed using the existing

USER_new_item_id user exit in the following method:
ItemImpl::finalizeCreateInputBase (Teamcenter::CreateInput * creInput )
Note

Whereas the USER_new_item_id user exit is used to create the ID

for a single item, the USER_new_item_ids user exit is used for bulk
creation of the IDs for all the associated objects that are created at the
same time as the item (revisions, forms, and so on).

validateCreateInput operation
Override this operation to implement any special business logic code for
validating the CreateInput. You can use it to perform uniqueness validation,
for example, the item_id input is unique.

setPropertiesFromCreateInput operation
Override this operation to implement any special business logic code for
populating the POM instance. Use it to:

2-14

Populate input values onto the corresponding attributes of the POM

instance. (This is implemented generically at the POM_object level.)

Populate or initialize special attributes in terms of special business logic.

(This should be avoided.)

createPost operation

Server Customization Programmers Guide

PLM00074 J

Data-model-based customization

Override this operation to implement any special business logic code for creating
compounded objects.
o

Create compound objects or secondary objects.

Assign compound or secondary objects to the primary object through

references or GRM relations.

For example, the master form and item revision on an Item business object
are created in:
ItemImpl::createPostBase( Teamcenter::CreateInput * creInput )

For instructions about how to override operations, see the Business Modeler IDE
Guide.
Note

The create operation logically creates objects and the save operation commits
the changes to the database. This pattern must be followed whenever
the object creation is initiated. Following this pattern requires that any
postactions on the create operation should not assume the existence of the
objects in the database. If database interactions like queries or saving to the
database against the newly created objects are needed in the postactions,
they must be attached as a postaction to the save message and not the
create message. The save message is initiated following the create or modify
operation. There is a mechanism to distinguish between the two cases.
Beginning in Teamcenter 9.1, it is mandatory that the postactions of
the create operation must not access the database as described. If any
such postactions are found, they must be moved or refactored to the save
operation.
For complete instructions, see the Business Modeler IDE Guide.

Implement the create operation on a new business object

1. Use the Operation Descriptor tab on the new business object to configure its
creation properties.
For more information about using this tab, see the Business Modeler IDE Guide.
2. Override the child operations on the create operation in the Operations tab
for the new business object.
For more information about these operations, see The create operation.
3. Generate the C++ code in the Advanced perspective by right-clicking your project
folder in the Business Objects view and choosing Generate CodeC++ classes.
4. Implement custom create business logic in the generated Impl file.
For more details about how to perform these commonly performed customization
tasks, see Basic tasks for data-model-based customization.

PLM00074 J

Server Customization Programmers Guide

2-15

Chapter 2

Data-model-based customization

Call Teamcenter C++ API

You can call the standard Teamcenter C++ API in your C++ implementation code.
For more information about the Teamcenter C++ API, see the C++ API Reference.
When you reference Teamcenter C++ API, typically, the customization code starts
with a tag_t tag, then constructs a business object reference with the itemTag tag,
and finally calls the C++ API, as in the following example:
#include <metaframework/BusinessObjectRef.hxx>
#include <fclasses/ifail.hxx>
#include <tccore/Item.hxx>
typedef
#define
#define
#define

unsigned int tag_t;

ITK_ok 0
EMPTY_ITEM_ID 101; // error code to be defined
UNKNOWN_ERROR 201; // error code to be defined

int setWsoObjectDescAndCheckItemId (tag_t itemTag, const std::string& description)

{
int ifail = ITK_ok;
// create a smart pointer of Item Type from object tag
BusinessObjectRef<Teamcenter::Item> item(itemTag);
try
{
if (description.empty())
{
// execute Teamcenter::WorkspaceObject::setObject_desc method
// Note that WorkspaceObject is the parent BusinessObject of Item
if ((ifail = item->setObject_desc(description, true)) != ITK_ok )
{
return ifail;
}
}
else
{
// execute Teamcenter::WorkspaceObject::setObject_desc method
if (( ifail=item->setObject_desc(description))!= ITK_ok)
{
return ifail;
}
}
std::string itemId;
bool isNull = false;
// execute Teamcenter::Item::getItem_id method
if ((ifail = item->getItem_id( itemId, isNull))!= ITK_ok )
{
return ifail;
}
if ( isNull )
{
return EMPTY_ITEM_ID; // empty item_id
}
}
catch ( IFail &ex )
{
return ex;
}
catch (...)
{
printf ("\n uncepted exception captured; please report errors. \n");
return UNKNOWN_ERROR;
}
return ITK_ok;

2-16

Server Customization Programmers Guide

PLM00074 J

Chapter

Teamcenter Services
customization

Introduction to Teamcenter Services customization . . . . . . . . . . . . . . . . . . . . 3-1

Enable Teamcenter Services customization . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Basic tasks for Teamcenter Services customization . . . . . . . . . . . . . . . . . . . . 3-2
Add Teamcenter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Connect a client to Teamcenter Services . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

PLM00074 J

Server Customization Programmers Guide

Chapter

Teamcenter Services
customization

Introduction to Teamcenter Services customization

Teamcenter Services are a collection of Teamcenter operations. Teamcenter Services
are used to integrate your companys applications to Teamcenter.
Services are organized as follows:

Operations
Define discrete functions, such as create, checkin, checkout, and so on.
Operations are used for all internal Teamcenter actions and are called by
external clients to connect to the server.

Services
Organize operations into groups having to do with a specific area.

Libraries
Place similar services together.

Teamcenter ships with service libraries and interfaces to build applications in

Java, C++, and C# (.NET), allowing you to choose the method that best fits with
your environment. Teamcenter also ships with WS-I compliant WSDL files for all
operations. To see these libraries, see the soa_client.zip file on the installation
source.
For more information, see the Services Guide and the Services Reference.
Note

The Services Reference is available only in the Teamcenter HTML Help

Collection. It is not available in the PDF collection.

Enable Teamcenter Services customization

To enable Teamcenter Services customization, configure the Business Modeler IDE
to create services and write the implementation code.
For complete instructions, see the Business Modeler IDE Guide.
1. Install the Business Modeler IDE.
In the Solutions panel of the Teamcenter Environment Manager (TEM), select
Business Modeler IDE.

PLM00074 J

Server Customization Programmers Guide

3-1

Chapter 3

Teamcenter Services customization

During installation, you are asked to enter the location of a Java Development
Kit (JDK) on your system. After installation, verify that the JDK is set in the
install-location\bmide\client\bmide.bat file, for example:
set JRE_HOME=C:\Program Files (x86)\Java\jre7
set JAVA_HOME=C:\Program Files (x86)\Java\jdk1.7.0
set JDK_HOME=C:\Program Files (x86)\Java\jdk1.7.0

2. Create a project in the Business Modeler IDE.

Choose FileNewProject, and in the New Project dialog box, choose Business
Modeler IDENew Business Modeler IDE Template Project.
As you work through the wizard, ensure that you fill in the Code Generation
Information dialog box and the Build Configuration Information dialog box.
3. Set up the services creation environment in the Business Modeler IDE.
Create the following objects:

Release
In the Extensions view of the Advanced perspective, choose Code
GenerationReleases, right-click the Releases folder, and choose New
Release.
Ensure that you select the Set as Current Release check box to indicate that
this release is the active one to use for your new services. In the Service
Version box, type the version of the services you plan to create in the release
using format _YYYY_MM, for example, _2011_10. You must fill in the
Service Version box if you plan to create services for this release.

Service library
In the Extensions view, choose Code GenerationServices, right-click the
Services folder and choose New Service Library.

After the environment is set up, you are ready to create services.
For more information, see Basic tasks for Teamcenter Services customization.

Basic tasks for Teamcenter Services customization

To perform basic Teamcenter Services customization tasks, use the Business Modeler
IDE to create services, services operations, and to write services implementation
code.
For complete instructions, see the Business Modeler IDE Guide.
Use Teamcenter Services samples as a guideline to create your own clients to connect
to the server-side services.
For more information, see the Services Guide.

Add Teamcenter Services

Use the Business Modeler IDE to add Teamcenter Services and operations.
For complete instructions, see the Business Modeler IDE Guide.

3-2

Server Customization Programmers Guide

PLM00074 J

Teamcenter Services customization

1. Add a service.
In the Extensions view of the Advanced perspective, expand the Code
GenerationServices folders, right-click the service library in which you want
to create the new service, and choose New Service.
2. Add service data types (if needed). Service data types are used by service
operations as return data types and can also be used as parameters to operations.
Right-click the service, choose Open, click the Data Types tab, and click the
Add button.
3. Add service operations.
Right-click the service, choose Open, click the Operations tab, and click the
Add button.
4. Generate service artifacts.
Right-click the Code GenerationServices folder and choose Generate
CodeService Artifacts. To generate code only for a particular service library,
select only the service library.
5. Write implementations of the service operations.
To see the generated files, right-click in the Navigator view and choose
Refresh. By default, the generated service artifacts are placed in the Source
Folder\service-library folders.
Write implementations in the generated serviceimpl.cxx files where it contains
the text: TODO implement operation.
6. Build the libraries containing server code.
In the Navigator view, right-click the project and choose Build
ConfigurationsBuildAll.
7. Package your template.
Choose FileNewOther, and in the New dialog box, choose Business Modeler
IDEPackage Template Extensions. This packages your changes into a
template that can be installed to a test server.
Note

You cannot use live update to distribute codeful customizations to a

server.

8. Install the template to a test server to verify the new functionality.

After packaging, copy the resulting files from your project\output\packaging
directory to a directory on the test server where you want to install the template.
Using the Teamcenter Environment Manager (TEM), in the Features panel,
click the Browse button on the lower right side of the panel to browse to the
directory where you have copied the template files.

Connect a client to Teamcenter Services

Use Teamcenter Services samples as a guideline to create your own clients to connect
to the server-side Teamcenter Services.

PLM00074 J

Server Customization Programmers Guide

3-3

Chapter 3

Teamcenter Services customization

You can use the services sample client applications as a guideline to configure
your own clients. Sample clients are provided in the soa_client.zip file on the
Teamcenter software distribution image. When you unzip the soa_client.zip file,
the cpp, java, and net folders are created, and under each is a samples folder that
contains sample clients. For more information about how to configure your own
client, look at the source files provided with the samples.
For more information, see the Services Guide.

3-4

Server Customization Programmers Guide

PLM00074 J

Chapter

PLM00074 J

ITK customization

Introduction to the ITK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Basic concepts for ITK customization . . . . . . . . . . . . . . . . . . .
Syntax conventions used in this guide . . . . . . . . . . . . . . . .
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Variable naming conventions . . . . . . . . . . . . . . . . . . . . . .
Class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Include files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Special data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic tasks for ITK customization . . . . . . . . . . . . . . . . . . . . .
Configure Visual Studio to build and debug ITK applications
Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Journal files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
System logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Memory management . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initializing modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking user exits and server exits . . . . . . . . . . . . . . . . . .
Link user exits in UNIX and Linux . . . . . . . . . . . . . . .
Link user exits in Windows . . . . . . . . . . . . . . . . . . . . .
Export new symbols from libuser_exits.dll on Windows .
Linking stand-alone programs . . . . . . . . . . . . . . . . . .
Run the executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Upgrading your ITK programs . . . . . . . . . . . . . . . . . . . . .
Batch ITK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Batch program template . . . . . . . . . . . . . . . . . . . . . . .
Compile and link batch programs . . . . . . . . . . . . . . . .
Custom exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Build the library file . . . . . . . . . . . . . . . . . . . . . . . . .
Register custom callbacks . . . . . . . . . . . . . . . . . . . . . .
Register user exits customization . . . . . . . . . . . . . . . .
Execute multiple customizations . . . . . . . . . . . . . . . . .
Register customizations . . . . . . . . . . . . . . . . . . . . . . .
Register run-time properties using custom hooks . . . . .
Core functions . . . . . . . . . . . . . .
File relocation . . . . . . . . . . . .
Relocating datasets . . . . .
Add an action handler
Sample programs . . . . . .
smp_cr_mv_hl.c . . . . .

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

4-1
4-1
4-1
4-2
4-3
4-4
4-4
4-5
4-6
4-6
4-12
4-12
4-13
4-13
4-14
4-15
4-15
4-15
4-16
4-16
4-17
4-18
4-19
4-20
4-20
4-20
4-20
4-21
4-21
4-22
4-22
4-23
4-23
4-25
4-25
4-28

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

4-29
4-29
4-29
4-29
4-30
4-30

Server Customization Programmers Guide

smp_cr_mv_fl.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compile and execute smp_cr_mv_hl.c and smp_cr_mv_fl.c
sample_cr_move_files_main.c . . . . . . . . . . . . . . . . . . . .
Compile and execute sample_cr_move_files_main.c and
smp_cr_mv_fl.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Change the revisioning scheme . . . . . . . . . . . . . . . . . . . . . . . .
General hints about property coding . . . . . . . . . . . . . . . . . . . . .
Memory allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Method arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PROP_init_value_msg . . . . . . . . . . . . . . . . . . . . . . . . .
PROP_ask_value_type_msg . . . . . . . . . . . . . . . . . . . . .
PROP_set_value_type_msg . . . . . . . . . . . . . . . . . . . . . .
Value caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Persistent Object Manager layer . . . . . . . . . . . . .
Persistent Object Manager . . . . . . . . . . . . . . .
Concepts . . . . . . . . . . . . . . . . . . . . . . . . .
Class . . . . . . . . . . . . . . . . . . . . . . . .
Attribute . . . . . . . . . . . . . . . . . . . . . .
Instance . . . . . . . . . . . . . . . . . . . . . .
Index . . . . . . . . . . . . . . . . . . . . . . . .
Tag . . . . . . . . . . . . . . . . . . . . . . . . . .
Data manipulation services . . . . . . . . . . .
Create instance . . . . . . . . . . . . . . . . .
Copy instances . . . . . . . . . . . . . . . . .
Save instances . . . . . . . . . . . . . . . . . .
Load instances . . . . . . . . . . . . . . . . .
Unload instance . . . . . . . . . . . . . . . .
Refresh instances . . . . . . . . . . . . . . .
Delete instances . . . . . . . . . . . . . . . .
Order instance . . . . . . . . . . . . . . . . .
Reference of instance . . . . . . . . . . . . .
Instances of class . . . . . . . . . . . . . . . .
Class of instances . . . . . . . . . . . . . . .
Inquiries to find instances . . . . . . . . .
Attribute manipulation . . . . . . . . . . . . . .
Modifying attributes in the database . .
Setting attributes of loaded instances .
Getting attributes of loaded instances .
Tag, class_id, and attr_id manipulation
Variable length array manipulation . . .
Check reference . . . . . . . . . . . . . . . . .
Users and groups . . . . . . . . . . . . . . . . . .
Create . . . . . . . . . . . . . . . . . . . . . . .
Initialize . . . . . . . . . . . . . . . . . . . . . .
Delete . . . . . . . . . . . . . . . . . . . . . . . .
Set group . . . . . . . . . . . . . . . . . . . . .
Set user status and license level . . . . .
User and group inquiries . . . . . . . . . .
Application protection . . . . . . . . . . . . . . .
System utilities . . . . . . . . . . . . . . . . . . . .
Starting and stopping POM . . . . . . . .
Password manipulation . . . . . . . . . . .

Server Customization Programmers Guide

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. . . . . . . 4-30
. . . . . . . 4-30
. . . . . . . 4-31
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

4-31
4-31
4-31
4-31
4-32
4-32
4-32
4-32
4-32
4-33

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

4-33
4-33
4-33
4-33
4-34
4-34
4-34
4-35
4-35
4-35
4-36
4-36
4-36
4-37
4-37
4-38
4-38
4-38
4-38
4-39
4-39
4-40
4-40
4-40
4-41
4-41
4-41
4-42
4-42
4-42
4-43
4-43
4-44
4-44
4-44
4-45
4-46
4-46
4-46

PLM00074 J

Rollback . . . . . . . . . . . . . . . . . . . . . . . . . .
Time-outs . . . . . . . . . . . . . . . . . . . . . . . . .
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Control of logons . . . . . . . . . . . . . . . . . . . .
Environmental information . . . . . . . . . . . .
Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . .
SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Direct SQL access to the internal structure .
Other functions available for user assistance
POM enquiry module . . . . . . . . . . . . . . . . . . . . . .
Differences between old and new systems . . . . .
How do I use it? . . . . . . . . . . . . . . . . . . . . . . .
Basic concepts . . . . . . . . . . . . . . . . . . . . . .
Basic steps to creating queries . . . . . . . . . .
Basic single table enquiry . . . . . . . . . . . . . .
Classes and attributes in POM queries . . . .
Compound properties and POM enquiry . . .
Housekeeping . . . . . . . . . . . . . . . . . . . . . .
How to do a simple join . . . . . . . . . . . . . . .
More advanced use . . . . . . . . . . . . . . . . . . . . .
Query specification . . . . . . . . . . . . . . . . . .
Building expressions . . . . . . . . . . . . . . . . .
Practical example . . . . . . . . . . . . . . . . . . .
SELECT clause . . . . . . . . . . . . . . . . . . . . .
FROM clause . . . . . . . . . . . . . . . . . . . . . .
WHERE clause . . . . . . . . . . . . . . . . . . . . .
ORDER BY clause . . . . . . . . . . . . . . . . . . .
GROUP BY clause . . . . . . . . . . . . . . . . . . .
HAVING clause . . . . . . . . . . . . . . . . . . . . .
Subqueries . . . . . . . . . . . . . . . . . . . . . . . .
Use of class_alias . . . . . . . . . . . . . . . . . . . .
Use of pseudo_class . . . . . . . . . . . . . . . . . .
Use of Set-Expression . . . . . . . . . . . . . . . .
Special operators . . . . . . . . . . . . . . . . . . . .
Supported operators . . . . . . . . . . . . . . . . . .
Use of POM load by enquiry . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

4-46
4-47
4-47
4-47
4-47
4-48
4-48
4-48
4-49
4-49
4-50
4-50
4-50
4-51
4-52
4-52
4-53
4-53
4-54
4-54
4-56
4-56
4-57
4-58
4-59
4-59
4-60
4-61
4-61
4-61
4-62
4-63
4-64
4-66
4-68
4-70

Customize text and error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-70

ITK customization for Teamcenter applications . . . . . . . . . . . . . . . . . . .
Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating custom logic for autocomputing Classification attribute
values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teamcenter mechatronics process management . . . . . . . . . . . . . . . .
Mechatronics Process Management fundamental objects . . . . . . .
Object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Harness model support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mechatronics Process Management API modules . . . . . . . . . . . .
API use examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating functionality and functionality revision objects . . . .
Creating interface port objects . . . . . . . . . . . . . . . . . . . . . .
Defining ports for a functionality object . . . . . . . . . . . . . . . .
Creating connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Listing connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PLM00074 J

. . . . 4-72
. . . . 4-72
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

4-72
4-75
4-75
4-76
4-77
4-77
4-78
4-79
4-79
4-80
4-80
4-82

Server Customization Programmers Guide

Disconnecting ports from a connection . . . . . . . . . . . . . . . . . . . . . 4-82

Removing specific ports from a connection . . . . . . . . . . . . . . . . . . 4-82
Creating process variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-82
Creating signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-83
Creating signal-process variable associations . . . . . . . . . . . . . . . . 4-83
Establishing signal associated system relations . . . . . . . . . . . . . . 4-83
Removing the relation between a signal/process variable and associated
system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-84
Maintaining redundant signals . . . . . . . . . . . . . . . . . . . . . . . . . . 4-85
Removing redundant signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-85
Setting signal values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-85
Setting signal characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-86
Setting signal line values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-86
Allocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-87
Object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-87
Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-88
API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-89
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-89
Embedded Software Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-89
Product structure management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-93
Bill of Materials (BOM) module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-94
Producing a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-94
Occurrence sequencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-95
Editing the BOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-96
Sample BOM program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-97
Occurrences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-101
Options and variations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-101
BOM Compare functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-107
Scope of compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-107
Defining a compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-107
BOM Compare execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-111
Advanced definition concepts . . . . . . . . . . . . . . . . . . . . . . . . . . 4-112
Advanced execution concepts . . . . . . . . . . . . . . . . . . . . . . . . . . 4-115
Performing a compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-117
BOM Compare output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-118
Report output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-119
BOM Compare output suppression . . . . . . . . . . . . . . . . . . . . . . 4-120
Product Structure (PS) module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-122
Product Structure classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-122
Product Structure model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-129
Product structure Traversal Engine . . . . . . . . . . . . . . . . . . . . . 4-130
Sharing of data objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-132
Object import and export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-132
Object types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-133
Object ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-133
Export of released objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-134
Exporting objects the route . . . . . . . . . . . . . . . . . . . . . . . . . . 4-134
Responsibilities and restrictions when exporting . . . . . . . . . . . . 4-135
Import semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-136
Importing objects the route . . . . . . . . . . . . . . . . . . . . . . . . . . 4-136
Restrictions when importing . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-137
Object import and export interface . . . . . . . . . . . . . . . . . . . . . . 4-138
PLM XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-138
Using ITK and PLM XML to export a BOM view revision . . . . . . 4-139

Server Customization Programmers Guide

PLM00074 J

Customizing action rules . . . . . . . . . . . . . . . . . . . . . .

Customizing filter rules . . . . . . . . . . . . . . . . . . . . . . .
Setting the target path name . . . . . . . . . . . . . . . . . . .
Data Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exchanging data between Teamcenter and Teamcenter
Enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Briefcase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TIE framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multi-Site Collaboration . . . . . . . . . . . . . . . . . . . . . . . . .
Transferring site ownership . . . . . . . . . . . . . . . . . . . .
Mapping application-specific IDs using Object Directory
extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Legacy ITK considerations . . . . . . . . . . . . . . . . . . . . .
USER_is_dataset_exportable user exit . . . . . . . . . . . . .
Customizing system administration modules . . . . . . . . . . . . . .
Customize Audit Manager . . . . . . . . . . . . . . . . . . . . . . . .
Customize Vendor management . . . . . . . . . . . . . . . . . . . .
Customize Volume Management . . . . . . . . . . . . . . . . . . . .
Customize Report Builder . . . . . . . . . . . . . . . . . . . . . . . .
Customize subscriptions . . . . . . . . . . . . . . . . . . . . . . . . .
Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enterprise Process Modeling . . . . . . . . . . . . . . . . . . . . . .
EPM object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Action handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Business rule handlers . . . . . . . . . . . . . . . . . . . . . . . .
Customizing a procedure with EPM . . . . . . . . . . . . . . . . .
Writing your own action handler . . . . . . . . . . . . . . . . .
Writing your own rule handler . . . . . . . . . . . . . . . . . .
Using validation rules . . . . . . . . . . . . . . . . . . . . . . . .
EPM hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Perform action handlers . . . . . . . . . . . . . . . . . . . . . . .
Branching in your handler . . . . . . . . . . . . . . . . . . . . .
Avoiding infinite loops in perform actions . . . . . . . . . . .

PLM00074 J

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

4-141
4-143
4-144
4-145

.......
.......
.......
.......
.......
Services
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......
.......

4-145
4-145
4-146
4-147
4-147
4-148
4-148
4-149
4-150
4-150
4-151
4-152
4-152
4-154
4-157
4-157
4-158
4-158
4-159
4-159
4-162
4-162
4-163
4-163
4-165
4-167
4-171
4-171
4-171
4-171

Server Customization Programmers Guide

Chapter

ITK customization

Introduction to the ITK

The Integration Toolkit (ITK) is a set of software tools provided by Siemens PLM
Software that you can use to integrate third-party or user-developed applications
with Teamcenter. The ITK is a set of C functions used directly by Teamcenter and
NX.
For reference information about ITK APIs, see the Integration Toolkit Function
Reference. (The Integration Toolkit Function Reference is not available in PDF
format. It is available only in the Teamcenter HTML Help Collection.)
Note

Siemens PLM Software recommends that instead of using ITK for server
customization, you should use the data model customization method. The
data model framework is the structure used by Teamcenter itself.
For more information, see Introduction to data-model-based customization.

Basic concepts for ITK customization

Before performing ITK customizations, you should be aware of some basic concepts.
Syntax conventions used in this guide
This guide 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 type exactly as
shown.
In the preceding example, you type 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.

PLM00074 J

Server Customization Programmers Guide

4-1

ITK customization

Chapter 4

[]

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

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

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

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] */ );

4-2

int

Nearly all ITK functions return an integer error code. This

code can be passed to the EMH_ask_error_text 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.

type

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

tag_t*, or char***).

Server Customization Programmers Guide

PLM00074 J

ITK customization

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.

Variable naming conventions

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

Typedefs end in _t.

Constants end in _c.

Enums end in _e.

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

The following constants have a length of 128; therefore, class attributes

can contain 128 bytes:

ITEM_id_size_c

ITEM_name_size_c

WSO_name_size_c

Beginning in Teamcenter 10.1, these fixed-size buffer ITK APIs are

deprecated.
Many of the Integration Toolkit (ITK) APIs in Teamcenter are based on
fixed-size string lengths. As long as Teamcenter is operating in a deployment
scenario where each character occupies only one byte (such as western
European languages), there are not any issues. However, when Teamcenter
is deployed in a scenario where each character can occupy multiple
bytes (such as Japanese, Korean, or Chinese), data truncation can occur.
Therefore, the fixed-size buffer ITK APIs are deprecated, and wrapper APIs
are provided for each of the fixed-size buffer APIs.

PLM00074 J

Server Customization Programmers Guide

4-3

Chapter 4

ITK customization

Siemens PLM Software recommends that you refactor any customizations

that use the older fixed-size buffer APIs and replace them with the new
APIs. The new APIs use the char* type instead of fixed char array size in
the input and output parameters. The new APIs use dynamic buffering to
replace the fixed-size buffering method.
For a list of the deprecated ITK APIs and their replacements, see the
Deprecated tab in the Integration Toolkit Function Reference.
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.
Caution

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
folder class, you can pass instances of it to FL functions.
Include files
All ITK programs must include tc/tc.h. It has the prototype for ITK_init_module
and the definition of many standard datatypes, constants, and functions that almost
every ITK program requires, such as tag_t and ITK_ok.
The include files are located in subdirectories of the TC_ROOT/include directory.
You must include the subdirectory when calling the include file. For example, when
calling the epm.h include file, which is located in the epm subdirectory, you must
call it as:
#include <epm/epm.h>

All of the other ITK functions have their prototypes and useful constants and types
in a file called classname.h. In addition there are header files for many of the major
modules that contain constants and include all of the header files for the classes in
that module. Sometimes this header file is required, sometimes it is just convenient.
The Integration Toolkit Function Reference tells you which header files are required.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

For example, you could use this statement:

#include <sa/sa.h>

Or you could use these statements:

#include <sa/am.h>

4-4

Server Customization Programmers Guide

PLM00074 J

ITK customization

#include
#include
#include
#include
#include
#include
#include

<sa/sa_errors.h>
<sa/person.h>
<sa/role.h>
<sa/group.h>
<sa/groupmember.h>
<sa/user.h>
<sa/site.h>

There is also an error include file for every module called module_errors.h or
sometimes classname_errors.h. These files all contain error offsets from a value
assigned in the tc/emh_const.h file. One exception is POM, which has its errors in
the pom/pom/pom_errors.h file.
Teamcenter also comes with a set of include files that mimic standard C include files.
For example, instead of using:
#include "stdarg.h"

You could use:

#include <fclasses/tc_stdarg.h>

These include files are used in Teamcenter to insulate it from the operating system.
Sometimes the files include the system files directly, but other times system
dependencies are handled in the tc_ include files, thus enabling the Teamcenter
source code and yours to remain system independent. The files provided are:
fclasses/tc_ctype.h
fclasses/tc_errno.h
fclasses/tc_limits.h
fclasses/tc_math.h
fclasses/tc_stat.h
fclasses/tc_stdarg.h
fclasses/tc_stddef.h
fclasses/tc_stdio.h
fclasses/tc_stdlib.h
fclasses/tc_string.h
fclasses/tc_time.h
fclasses/tc_types.h
fclasses/tc_unixio.h
Special data types
All objects in the ITK are identified by tags of C type tag_t. A run-time unique
identifier isolates the client code using the object from its representation in memory,
making it safe from direct pointer access.
Tags may be compared by use of the C language == and != operators. An unset tag_t
variable is assigned the NULLTAG null value. If two tags have the same value, they
reference the same object. For example:
#include <tc/tc.h>
#include <ae/ae.h>
{
tag_t dataset_tag;
int error_code;
login, etc. ...
error_code = AE_find_dataset ("my special dataset", &dataset_tag)
if( error_code ==ITK_ok )
{ if (dataset_tag == NULLTAG)
{ /*

PLM00074 J

Server Customization Programmers Guide

4-5

ITK customization

Chapter 4

* Could not find my special dataset, so go create one.

*/
error_code = AE_create_dataset_with_id (....
}
}
else
{
report error ....

Basic tasks for ITK customization

Basic ITK customization tasks are those commonly performed on a regular basis
during your ITK work process.
Configure Visual Studio to build and debug ITK applications
Currently, the Teamcenter ITK build tools are provided in the form of script files
such as compile.bat and linkitk.bat. These script files do not take advantage of
the many powerful features available in Visual Studio IDE, such as the debugger,
symbol browsing, and project management. The following steps show you how to
configure Visual Studio to build debug and release versions of an ITK application
and use the debugger to debug the application.
Prerequisites:

A Teamcenter installation

Visual Studio 2010 Service Pack 1 installed

ITK sample files installed using Teamcenter Environment Manager (TEM)

1. Create the ITK project.

a. Start the Visual Studio IDE and create an empty project named itk_sample.

Sample ITK project

4-6

Server Customization Programmers Guide

PLM00074 J

ITK customization

b.

Copy the
TC_ROOT\sample\utilities\find_recently_saved_item_rev_itk_main.c
file to the itk_sample\itk_sample folder.

c.

In the Solution Explorer view, right-click the Source

Files folder and choose AddExisting Item. Select the
find_recently_saved_item_rev_itk_main.c file and click
Add.
At this point, you have a basic ITK project.

2. Set up the project properties to compile and link the ITK sample code.
a. In Visual Studio, the compiler and linker settings are managed are through
project property sheets. Following is an XML project property sheet that
contains the general properties to build both debug and release ITK
applications.
Open a text editor and cut and paste the following XML text into a new file:
<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<_ProjectFileVersion>10.0.40219.1</_ProjectFileVersion>
<_PropertySheetDisplayName>itk_general_exits</_PropertySheetDisplayName>
</PropertyGroup>
<ItemDefinitionGroup>
<ClCompile>
<AdditionalIncludeDirectories>TC_ROOT\include;TC_ROOT\include_cpp;%(AdditionalIncludeDirectories)
</AdditionalIncludeDirectories>
<PreprocessorDefinitions>NT40;POMDLL;CRTAPI1=_cdecl;CRTAPI2=cdecl;_WIN32;WIN32;WIN32_LEAN_AND_MEAN;WNT;
BYPASS_FLEX;_INTEL=1;IPLIB=none;%(PreprocessorDefinitions)</PreprocessorDefinitions>
</ClCompile>
<Link>
<AdditionalOptions>/ignore:4099 /ignore:4199 %(AdditionalOptions)</AdditionalOptions>
<AdditionalDependencies>itk_main.obj;libsyss.lib;libpom.lib;libtcsso.lib;libae.lib;libappr.lib;
libarchive.lib;libbackup.lib;libbom.lib;libcfm.lib;libconstants.lib;libcxpom.lib;libdmi.lib;
libecm.lib;libeint.lib;libepm.lib;libfclasses.lib;libform.lib;libgms.lib;libgrm.lib;libtcinit.lib;
libtc.lib;libtccore.lib;libtctrushape.lib;libinternal_exits.lib;libvalidation.lib;libitk.lib;liblov.lib;
libme.lib;libmgc.lib;libobjio.lib;libpie.lib;libai.lib;libproperty.lib;libps.lib;libpublication.lib;
libqry.lib;libclips.lib;libclipsutil.lib;librbf.lib;
libce.lib;libres.lib;libsa.lib;libss.lib;libstep.lib;
libsub_mgr.lib;libtextsrv.lib;libtie.lib;libnxmgr_im.lib;libaie.lib;
libics.lib;libeintstub.lib;libsml.lib;libuser_exits.lib;librdv.lib;libcollabctx.lib;
libmechatronics.lib;libtccoreext.lib;libusagewc.lib;libusage.lib;
libcontmgmt.lib;libtc_utils.lib;libschmgt.lib;libschmgt_bridge.lib;
libdocmgt.lib;libdocmgtapp.lib;libvm.lib;libadsfoundationdispatch.lib;libcm.lib;libcmdispatch.lib;
libconstants.lib;libbase_utils.lib;libmld.lib;libfunctionality.lib;
libmfg.lib;libmfgbvr.lib;libtcserverutil.lib;libcondvalidation.lib;libbooleanmath.lib;
libconfigurator.lib;libfnd0booleansolve.lib;libsecore.lib;libFnd0formulamgmt.lib;%(AdditionalDependencies)
</AdditionalDependencies>
<AdditionalLibraryDirectories>TC_ROOT\lib;%(AdditionalLibraryDirectories)</AdditionalLibraryDirectories>
<DelayLoadDLLs>libtcsso.dll;libict.dll;libae.dll;libappr.dll;libarchive.dll;libbackup.dll;libbom.dll;
libcfm.dll;libdmi.dll;libecm.dll;libeint.dll;libepm.dll;libform.dll;
libgrm.dll;libtccore.dll;libtctrushape.dll;libinternal_exits.dll;libitk.dll;libvalidation.dll;
liblov.dll;libme.dll;libmechatronics.dll;libmgc.dll;libobjio.dll;libproperty.dll;libps.dll;
libpublication.dll;libqry.dll;libres.dll;libstep.dll;libsub_mgr.dll;
libtccoreext.dll;libnxmgr_im.dll;libpie.dll;libai.dll;%(DelayLoadDLLs)
</DelayLoadDLLs>
<SubSystem>Console</SubSystem>
<TargetMachine>MachineX86</TargetMachine>
</Link>
</ItemDefinitionGroup>
</Project>

Note

In this text, replace TC_ROOT with the path to your Teamcenter

installation.
This file is configured for 32-bit systems. If you are running a
64-bit system, change WIN32 to WIN64, and change MachineX86 to
MachineX64.

b.

PLM00074 J

After the XML file is in your editor, check the file:

Server Customization Programmers Guide

4-7

Chapter 4

ITK customization

Verify no line wrapping is occurring. Each property and value must be

on one line. For example, the values for AdditionalDependencies
must be on the same line.

Verify that spaces between library names are preserved.

Update the AdditionalIncludeDirectories and

AdditionalLibraryDirectories nodes to reflect your environment
paths.

Save the file as itk_general.props in the itk_sample\itk_sample folder.

c.

In the Visual Studio IDE, open the Property Manager view. Right-click the
Debug | Win32 node, choose Add Existing Property Sheet, and select the
itk_general.props file. Repeat this step for the Release | Win32 node.
Note

To set the project for 64-bit, right-click the project, choose Properties,
click the Configuration Manager button, and select x64 for the
platform.

Your Property Manager view should look something like the following.

Add existing property sheet

At this point, you are ready to build your ITK application.
d. Build either the debug or release target by setting the target and pressing
F7 to build.
3. Debug the ITK application.
a. Before you start the debugger, the Teamcenter environment variables must
be set for the ITK application to run correctly, for example, TC_ROOT,
FMS_HOME, and so on. There are several ways you can accomplish this
task; however, you can control and manage the Teamcenter environment
within the Visual Studio project. This way you can make changes to the
Teamcenter environment and keep the changes local to the Visual Studio
project.

4-8

Server Customization Programmers Guide

PLM00074 J

ITK customization

A. To get the required Teamcenter environment settings, use the following

script:
@echo off
set TC_ROOT=TC_ROOT
set TC_DATA=TC_DATA
call %TC_DATA%\tc_profilevars.bat

Replace TC_ROOT with the path to your Teamcenter installation, and

replace TC_DATA with the path to the TC_DATA directory.
B. Open a command shell and run the script.
C. Type the set > env.txt shell command to echo the entire Teamcenter
environment settings to the env.txt file. Open the text file into a text
editor and copy the entire file contents into the clipboard.
D. In the Solution Explorer view, right-click the itk_sample node and
choose Properties.
E. In the Configuration box, select All configurations.
F. Under Configuration Properties, select Debugging, and in the right
pane, select Environment. Click the ellipsis button () and paste the
copied Teamcenter environment text into the Environment dialog box.
Note

Remove unnecessary environment settings. The cleaner the

environment is, the less chance of unexpected results.

The Environment dialog box should look something like the following.

Environment dialog box

Click OK to save the environment.
G. Set Merge Environment to No.

PLM00074 J

Server Customization Programmers Guide

4-9

Chapter 4

ITK customization

H. Add and update the command line options to Command Arguments:

-u=user-name -p=password -start_date=date
-obj_type=ItemRevision -out_file=-

You can change the command line options as needed.

The finished property page should look something like the following.

Property page
I.

Because Teamcenter only provides release ITK libraries to link with, it is

best to use the Microsoft release run-time libraries when building the
debug target. This step eliminates linker warnings.
In the Configuration box, select Debug, and under C/C++Code
Generation in the Runtime Library box, select multi-threaded DLL /MD.

4-10

Server Customization Programmers Guide

PLM00074 J

ITK customization

Setting Runtime Library

J.

Click OK to save the project.

You are now ready to debug the ITK application.

b.

Run the debugger with break points.

A. Open the find_recently_saved_item_rev_itk_main.c file from the
Solution Explorer view. By pressing F9, set break points at the following
lines:

Set break points

B. Press F5 to start the debugger and launch the ITK application. The
debugger should break at the first break point; you can use F10 to step
over or F5 to continue to the next break point.

PLM00074 J

Server Customization Programmers Guide

4-11

Chapter 4

ITK customization

Debugging
You can use ITK debugging aids such as journal files and log files to understand
errors in your programs.
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 many
journaling flags in the system for the modules and ITK in general. Also, there are
flags for NONE and ALL. Another option is to set the TC_JOURNAL environment
variable to FULL, SUMMARY, or NONE.
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 can have ITK and EPM journaling on if you are working in
that area and leave POM and PS journaling off, ensuring that your journal file does
not get cluttered with unuseful information. The following code shows how the
POM logs input and output arguments:
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)

The following code 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,
@* application_name = Information Manager, descriptor = 0, n_attrs = 4,
@*
attr_ids = { 00650022, 00650023, 00650024,
00650025 } returns 0

4-12

Server Customization Programmers Guide

attr_ids)

PLM00074 J

ITK customization

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

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.
The following code 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_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

The journal information for lower level routines are nested inside the higher level
routines.
System logs
The system log can be useful in diagnosing errors because when a function returns
an error, it often writes extra information to the system log. 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.
Note

PLM00074 J

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Server Customization Programmers Guide

4-13

Chapter 4

ITK customization

Error handling
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 XML code and displayed in the error windows at the
user interface. EMH ITK functions are defined in the tc/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. (The Integration Toolkit Function Reference
is not available in PDF format. It is available only in the Teamcenter HTML Help
Collection.)
Note

Caution

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.
ITK extension rules cannot provide information or warning feedback
to users.
For example, if you want a warning dialog box to appear after an
operation is done, you cannot define the warning in ITK extension rule
code because of the code processing order:
1. Teamcenter code is executed.
2. The custom code is executed.
3. Teamcenter code is executed.
For example, you put the following into the extension rule custom code:
EMH_store_error_s2(EMH_severity_warning, ITK_err,
"EMH_severity_warning", "ITK_ok");
return ITK_ok;

You place this code in step 2 because you want the Teamcenter
framework to proceed with step 3 so that when the whole execution is
done, the user receives a warning message in the client.
However, the only errors or warnings returned from a service operation
are the ones explicitly returned by the business logic of the service
implementation. This is typically done with code like this:
Try
{
....

4-14

Server Customization Programmers Guide

PLM00074 J

ITK customization

}
Catch( IFail& ifail)
{
serviceData.addErrorStack();
// This will add the current
IFail and whatever other errors/warnings are currently on the error store
}

The Teamcenter Services Framework does not look at the error store to
see if there are warnings or errors. Unless the exception moves up to the
Teamcenter (service implementation) code where it is caught, the error
or warning is lost.
Memory management
Frequently, memory is allocated by a Teamcenter function and returned to the caller
in a pointer variable. This is indicated in the code by the /* <OF> */ following the
argument definition. This memory should be freed by passing the address to the
MEM_free function. For example, to use the function:
int AE_tool_extent (
int* tool_count, /* <O> */
tag_t** tool_tags /* <OF> */
);

You should include the following code:

{
tag_t* tool_tags;
int tool_count;
int error_code;
int i;
error_code = AE_tool_extent &tool_count, &tool_tags);
if( error_code == ITK_ok )
{
for (i = 0; i < tool_count; i++)
{...}
MEM_free (tool_tags);
}
else
{
report the error
}
...

Initializing modules
You must either call the initialization function for all modules, ITK_init_module,
or the individual module initialization function, such as FL_init_module, before
using any of the functions in that module. If you do not, you get an error like
FL_module_not_initialized. The only reason that a module initialization should
ever fail is if the module requires a license and there is no license available.
You should also remember to exit modules. In some cases this could cause significant
memory to be freed. It may also free up a concurrent license for use by another user.
Compiling
Compile your program using the ANSI option. The ITK functions can also be called
from C++. Sample compile scripts are available in the TC_ROOT/sample directory.

PLM00074 J

Server Customization Programmers Guide

4-15

ITK customization

Chapter 4

Assuming the script name is compile, it can be used by executing the following
command.
TC_ROOT/sample/compile filename.c
The actual compile statements are as follows:

HP
cc filename.c -c -Aa filename.o -D_HPUX_SOURCE -DHPP -I$TC_INCLUDE

Solaris
cc -KPIC -DSUN -DUNX -D_SOLARIS_SOURCE -DSYSV +w
-I${TC_INCLUDE} -c filename.c -o filename.o

-Xc -O -I.

Linux
gcc -c -fPIC -m64 -DPOSIX -I${TC_INCLUDE} filename.c -o filename.o

Windows
If you are using Windows, you must supply the -DIPLIB=none argument to tell
the compile script that a stand-alone program object is being compiled:
$TC_ROOT/sample/compile -DIPLIB=none filename.c

When using Windows, use Visual Studio 2010 Service Pack 1 or later.
Linking user exits and server exits
When you create user exits or server exits, you must link them to libraries.
Link user exits in UNIX and Linux
User exits are places in the server where you can add additional behavior by
attaching an extension.
For additional information about ITK user exits, see the Integration Toolkit Function
Reference and the Business Modeler IDE Guide.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

To verify your UNIX or Linux environment and installation:

1. Set the Teamcenter environment. Set the TC_ROOT, TC_LIBRARY, and
TC_INCLUDE environment variables.
2. Create a user_exits and code directories.
3. Extract the objects with the following commands:
$ cd user_exits
$ ar -x $TC_ROOT/lib/libuser_exits.a

4. Complete your customization. It is good practice to include a printf statement

with a coding version and compile date. The following is a minimal example:
$ cd ../code

a. Copy all of the files that you want to modify (user_gsshell.c in the following
example):

4-16

Server Customization Programmers Guide

PLM00074 J

ITK customization

$ cp $TC_ROOT/sample/examples/user_gsshell.c .

b.

Make the required changes.

For example, include your own printf statement in the
USER_gs_shell_init_module function in the user_gsshell.c
file:
printf("\nCustom library for %s, version %s, compiled on %s %s\n\n",
customer, version, _DATE_, _TIME_);

c.

Create additional .c files as required, but see below for Windows

considerations when exporting new symbols from the library.

5. Compile your library objects and move them into the library directory:
$ $TC_ROOT/sample/compile *.c
$ cp *.o ../user_exits

6. Move into the library directory and link the library:

$ cd ../user_exits
$ $TC_ROOT/sample/link_user_exits

7. You now have a new libuser_exits.s file. Set the TC_USER_LIB command
to get Teamcenter to use it:
$ export TC_USER_LIB=pwd
$ $TC_BIN/tc

You see your printf messages after the Teamcenter copyright messages.
If the libuser_exits.so (or libuser_exits.sl on Hewlett-Packard) file compiles
without undefined symbols, then the installation and environment are correct.
Link user exits in Windows
User exits are places in the server where you can add additional behavior by
attaching an extension.
For additional information about ITK user exits, see the Integration Toolkit Function
Reference and the Business Modeler IDE Guide.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

To verify your Windows environment and installation:

1. Set the Teamcenter environment. Set the TC_ROOT, TC_LIBRARY, and
TC_INCLUDE environment variables.
2. Create a user_exits and code directories.
3. Extract the objects with the following commands:
$ cd user_exits
$ extract_objects %TC_ROOT%\lib\libuser_exits.ar.lib

PLM00074 J

Server Customization Programmers Guide

4-17

Chapter 4

ITK customization

4. Complete your customization. It is considered good practice to include a printf

statement with a coding version and compile date. The following is a minimal
example:
$ cd ../code

a. Copy all of the files that you want to modify (the user_gsshell.c file in the
following example):
$ cp $TC_ROOT/sample/examples/user_gsshell.c .

b.

Make the required changes.

For example, include your own printf statement in the
USER_gs_shell_init_module function in the user_gsshell.c
file:
printf("\nCustom library for %s, version %s, compiled on %s %s\n\n",
customer, version, _DATE_, _TIME_);

c.

Create additional .c files as required, but see below for considerations when
exporting new symbols from the library.

5. Compile your library objects and move them into the library directory:
%TC_ROOT%\sample\compile -DIPLIB=libuser_exits *.c
copy *.obj ..\user_exits

6. Move into the library directory and link the library. You do not need .def files:
cd ../user_exits
%TC_ROOT%\sample\link_user_exits

7. You now have new libuser_exits.dll and libuser_exits.lib files. Set the
TC_USER_LIB command to get Teamcenter to use it:
for /f "delims==" %i in (chdir) do set TC_USER_LIB=%i
%TC_BIN%\tc
Note

To run stand-alone programs against this libuser_exits.dll library, you

must link them against the corresponding libuser_exits.lib file.

You see your printf messages after the Teamcenter copyright messages.
Export new symbols from libuser_exits.dll on Windows
Windows requires all symbols exported from .dll files to be declared. This
mechanism is invisible to UNIX, which exports every extern as usual (so you do not
need two sets of source).
In each header file, declare new functions for export from the .dll file:
1. Enter #include <user_exits/libuser_exits_exports.h> as the last #include of
the header file before all declarations.
2. Enter USER_EXITS_API after the word extern to mark each function
declaration for export. This is called decoration.
3. Enter #include <user_exits/libuser_exits_undef.h> at the end of the header
file after all declarations (within any multiple include prevention preprocessing).

4-18

Server Customization Programmers Guide

PLM00074 J

ITK customization

In each source file defining new functions for export from the .dll file, ensure that
the .c file includes its own corresponding .h file, so the definitions in the .c file know
about the decorated declarations in the .h file. If you do not do this, the compiler
complains about missing symbols beginning with __int__ when you try to link
stand-alone code against the libuser_exits.lib file.
Now you can compile and link as normal (in other words, compile with
-DIPLIB=libuser_exits).
Linking stand-alone programs
When you link your program, you must include the itk_main.o file on the command
line. This file contains the main object for your ITK program. To make this work, all
of your ITK programs must begin like this:
int ITK_user_main(int argc, char* argv[])
{ int result;
/*
* We should use ITK_auto_login here.
*/
if( (result = ITK_auto_login()) == ITK_ok)
{
do what you need to do ...
result = ITK_exit_module();
}
return result;
}

The order of Teamcenter libraries is important or your code may not link. Also add
any additional object files you have created to the link script to include them in
the main executable. A sample linkitk script file exists in the TC_ROOT/sample
directory.
If the script name is linkitk, you can execute the script with the following command:
$TC_ROOT/sample/linkitk -o executable-name filename.o
Note

The linkitk.bat file contains only the core Teamcenter libraries. To call
server APIs from optional solutions, you must add the libraries from the
optional solutions to the linkitk.bat file. You must also ensure these
libraries are available in the TC_LIBRARY location.
For example, to add the libraries for the optional Content Management
solution, add the following lines near the end of the linkitk.bat file
(before the "-out:$EXECUTABLE.exe" line):
"$ENV{TC_LIBRARY}\\libcontmgmt.lib /delayload:libcontmgmt.dll ".
"$ENV{TC_LIBRARY}\\libcontmgmtbase.lib /delayload:libcontmgmtbase.dll ".
"$ENV{TC_LIBRARY}\\libcontmgmtbasedispatch.lib
/delayload:libcontmgmtbasedispatch.dll ".

For Linux, add the TC_ROOT\lib folder to the LD_LIBRARY_PATH

system environment variable to link custom programs, for example:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ TC_ROOT/lib

PLM00074 J

Server Customization Programmers Guide

4-19

Chapter 4

ITK customization

Run the executable

To run or execute the program, you must have Teamcenter system privileges (in
other words, an account on Teamcenter). If your program is called without the
ITK_auto_login function, supply the arguments for user, password and group. If
the ITK_auto_login function is used, the necessary arguments can come from
the command line. The specific style for entry is dependent on your code. In this
class, the standard procedure is as follows:
filename -u=user -p=password -g=group

Be careful to execute this command in a directory where additional files can be

created since session and log files are created at run time.
Upgrading your ITK programs
If you are upgrading from an earlier version of Teamcenter or Teamcenter
Engineering to the current version of Teamcenter, you may need to change your ITK
programs. All obsolete ITK functions need to be replaced in your programs. For the
list of obsolete functions, see the Teamcenter 10.1 Release Bulletin.
If you are using any deprecated functions, you should replace those functions as soon
as you can, because deprecated functions will be removed from a future version. For
the list of deprecated functions, see the Integration Toolkit Function Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

If you are upgrading from a pre-Teamcenter 2007 version and you used ITK
functions to create data model functions, you must remove those functions from your
programs. They are obsolete and may corrupt your data model if you continue to use
them. For more information, see the Upgrade Guide.
Batch ITK
You can create batch ITK programs that are executed on a command line. Batch
programs log onto the Teamcenter database using information on command line,
perform some actions, and then exit.
Batch program template
The following code shows a template for writing a batch program:
#include <tc/tc.h>
#define WRONG_USAGE 100001
void dousage()
{
printf("\nUSAGE: template -u=user -p=password -g=\"\" \n");
return;
}
int ITK_user_main(int argc, char* argv[])
{
int status;
char* usr = ITK_ask_cli_argument("-u=");/* gets user */
char* upw = ITK_ask_cli_argument("-p=");/* gets the password */
char* ugp = ITK_ask_cli_argument("-g=");/* what the group is */
char* help = ITK_ask_cli_argument("-h=");/* help option */
char *s;
if ( (help) )
{

4-20

Server Customization Programmers Guide

PLM00074 J

ITK customization

dousage();
return WRONG_USAGE ;
}
/* Example of must have... */
if (( !usr) || (!upw) || (!ugp))
{
dousage();
return WRONG_USAGE ;
}
ITK_initialize_text_services (0);
status = ITK_init_module( usr,upw,ugp);
if ( status != ITK_ok)
{
EMH_ask_error_text( status, &s);
printf("Error with ITK_init_module: %s \n",s);
MEM_free(s);
return status;
}
else printf("Logon to template succesful as %s.\n", usr);
JOURNAL_comment ("Preparing to list tool formats");
TC_write_syslog("Preparing to list tool formats \n");
/* Call your functions between here */
ITK_exit_module( TRUE);
return status;
}

Compile and link batch programs

Follow this sequence to generate executables for batch programs.
Caution

Make sure the TC_INCLUDE and TC_LIBRARY environment

variables are set correctly.

1. Compile the batch program with the compile script:

compile -DIPLIB=none filename.c

The -DIPLIB argument specifies the target library; use none for batch
programs.
2. Link your program with the system library with the linkitk script:
linkitk -o executable filename.obj file3.obj file2.obj

3. Execute the batch program:

If you use ITK_auto_login:

filename arguments

If you use ITK_init_module:

filename -u=user -p=password -g=group arguments

The compile and linkitk scripts are Teamcenter-specific scripts and are available
in the TC_ROOT/sample directory.
Custom exits
Custom exits (also known as supplier custom hooks) allow nonconflicting
customizations to co-exist.

PLM00074 J

Server Customization Programmers Guide

4-21

Chapter 4

ITK customization

You should use the Business Modeler IDE user exits to do this kind of
customization work. Only create your own custom exits if you cannot
accomplish your goals with user exits in the Business Modeler IDE.

Caution

Environment
All the user exit customizations of the site are built in the form of a single library,
called site-name.dll/so/sl.
For example, if the site name is cust1, the library is cust1.dll/so/sl. The
custom library site-name.dll/so/sl is linked with libuser_exits. Use the
link_custom_exits.bat file from the TC_ROOT/sample directory. All custom
stand-alone ITK utilities are linked with the site-name.dll/so/sl file instead of
libuser_exits as the customization is in the site-name.dll/so/sl file. To see the
customization, define the custom library name in the TC_customization_libraries
preference. Make sure the prefix and the library prefix are the same. Set the
preference in the Options dialog box, accessed from the Edit menu in My Teamcenter.
For additional information on setting preferences, see Getting Started with
Teamcenter.
Build the library file
1. Create a working directory (for example, cust1).
2. Copy all your user exits and server exits customization code to this directory.
3. Compile your object files inside this directory using the
TC_ROOT/sample/compile command with the -DIPLIB=NONE
option.
4. Build the dynamic linked/shared library with the link_custom_exits command.
For example:
link_custom_exits cust1
Note

Do not modify or rebuild the libuser_exits and libserver_exits

libraries with the custom code.

Do not unarchive the libuser_exits.ar.lib file. These object files are

not required to be linked with the cust1 library.

Any custom library that uses the USERARG_* ITK method requires
dependency over the COTS (standard) libict shared library. If you
build this custom library on the UNIX or Linux platforms, you
must modify the $TC_ROOT/sample/link_custom_exits script to
register dependency of your custom library on the libict library. For
example, add the following lines to the link_custom_exits script:
set optionalLibraries="-lict"
$LinkTC -o $customLibrary $objectFiles $optionalLibraries

This ensures that the custom library is loaded correctly even by

those standalone ITK programs that do not have explicit dependency
over the libict library.

4-22

Server Customization Programmers Guide

PLM00074 J

ITK customization

5. If you are using Windows, copy the .dll and .PDB files to the directory that
contains the .dll files. For example:
copy cust1.dll %TC_ROOT%\\bin\\.
copy cust1.pdb %TC_ROOT%\\bin\\.

If you are using UNIX, copy the shared library to the TC_USER_LIB directory
or put the cust1 directory in the shared library path (Hewlett-Packard:
SHLIB_PATH, Solaris: LD_LIBRARY_PATH).
Register custom callbacks
Create a site-name_register_calls.c file in the sites source code development area.
The following code shows an example:
#include <tccore/custom.h>
#include <user_exits/user_exits.h>
#include your-include-files
extern DLLAPI int cust1_register_callbacks()
{
CUSTOM_register_exit (site-name, Base User Exit Function, (CUSTOM_EXIT_ftn_t)
your-custom-function-name);
}

site-name_register_callbacks
This is the entry point to the custom library. This function is executed
after loading the custom library. Ensure that the site-name name is the
same as the value stored in the TC_customization_libraries preference.
For example, if the custom library is cust1, this function should be called
cust1_register_callbacks.

site-name argument to the CUSTOM_register_exit

site-name is also the same as the value stored in the
TC_customization_libraries preference.

Base user exit function

This string is the name of the base user exit against which the custom
function is registered. All the USER_ functions from the files provided in the
TC_ROOT/sample directory can be customized.

your-custom-function-name
This is the function pointer registered against the above base user exit. The
definition of this function does not need to exist in this file, it could be in another
file.

your-include-files
Add any custom include files needed during the compilation and linking of the
custom library.

Register user exits customization

Custom hooks provide you the ability to:

PLM00074 J

Execute only site customization

Execute site customization along with other customizations

Server Customization Programmers Guide

4-23

ITK customization

Chapter 4

Execute the default core functionality

The custom functions registered in the site-name_register_calls.c file should have

an integer pointer as the first argument. This integer pointer should return the
decision, indicating whether to execute only the current customization, execute all
customizations, or only the default core functionality. The following variables are
defined in the custom.h file in the TC_ROOT/include/tccore directory:
#define ALL_CUSTOMIZATIONS 2
#define ONLY_CURRENT _CUSTOMIZATION 1
#define NO_CUSTOMIZATIONS 0

The following code shows an example with the following conditions:

The site name is cust1.

The custom library is cust1.

A custom function is registered against the USER_new_dataset_name.

cust1_register_calls.c:
#include <tccore/custom.h>
#include <user_exits/user_exits.h>
#include <cust1_dataset.h>
#include <cust1_register_callbacks.h>
#include <cust1_register_callbacks.h>
extern DLLAPI int cust1_register_callbacks()
{
CUSTOM_register_exit (cust1, USER_new_dataset_name, (CUSTOM_EXIT_ftn_t)
CUST1_new_dataset_name);
}
cust1_register_callbacks.h:
extern DLLAPI int cust1_new_dataset_name (int *decision, va_list args);
cust1_dataset.c:
#include <cust1_register_callbacks.h>
#include <tccore/custom.h>
extern DLLAPI int CUST1_new_dataset_name (int *decision, va_list args)
{
/*
Expand the va_list using va_arg
The va_list args contains all the variables from USER_new_dataset_name.
*/
tag_t owner = va_arg (args, tag_t);
tag_t dataset_type = va_arg (args, tag_t);
tag_t relation_type = va_arg (args, tag_t);
const char* basis_name = va_arg (args, const char *);
char** dataset_name = va_arg (args, char **);
logical* modifiable = va_arg (args, logical *);
/*
if cust1 wants all other customizations to be executed, then set
*decision = ALL_CUSTOMIZATIONS;
elseif cust1 wants only its customization to be executed then set
*decision = ONLY_CURRENT_CUSTOMIZATION;
else if cust1 wants only base functionality to be executed, then set
*decision = NO_CUSTOMIZATIONS;
*/
/* Write your custom code
*/
return ifail;
}

4-24

Server Customization Programmers Guide

PLM00074 J

ITK customization

Note

The va_list argument in the CUSTOM_EXIT_ftn_t function should

match the arguments of the base user exit or server exit function in the
CUSTOM_register_exit function.

To register pre- or post-actions against Teamcenter messages, you must

use the USER_init_module method, for example:
CUSTOM_register_exit("lib_myco_exits", "USER_init_module",
(CUSTOM_EXIT_ftn_t)register_init_module);

For a pre- or post-action to be invoked during a call to a Teamcenter

Services operation, the custom extension must be registered against
the USER_init_module.
Execute multiple customizations
If your site wants to execute some other sites customization other than your
customization, follow these steps:
1. Both the cust1 and cust2 sites should follow the sections above to register
their customization for USER_ exits.
2. Both sites should build their cust1.dll/sl/so cust2.dll/sl/so custom libraries to
share them.
3. Neither site should rebuild the libuser_exits and libserver_exits.
4. Add the custom library names in the TC_customization_libraries preference
in the Options dialog box, accessed from the Edit menu in My Teamcenter:
TC_customization_libraries=
cust1
cust2

5. The preference values should match the library names. For example, the cust1
site should have the cust1.dll/sl/so file and the cust2 site should have the
cust2.dll/sl/so file.
6. The custom libraries of the cust1 and cust2 sites (which would be cust1.dll/sl/so
and cust2.dll/sl/so, respectively) should be in the library path:

LD_LIBRARY_PATH for Solaris or Linux

SHLIB_PATH for Hewlett-Packard

LD_LIBRARYN32_PATH for Silicon Graphics

PATH for Windows

Register customizations
There are four different functions you can use to register customizations, depending
on the situation:

PLM00074 J

CUSTOM_register_callbacks

CUSTOM_register_exit

Server Customization Programmers Guide

4-25

ITK customization

Chapter 4

CUSTOM_execute_callbacks

CUSTOM_execute_callbacks_from_library

CUSTOM_register_callbacks
This function registers customizations for all customization contexts registered in
the Options dialog box (accessed from the Edit menu in My Teamcenter):
int CUSTOM_register_callbacks ( void )

This function loads the custom library and calls the entry point function pointer to
register custom exits. The entry point function contains the custom registrations
for the required USER_ exits.
CUSTOM_register_exit
This ITK function should be called only in the USER_preint_module function in
the user_init.c file. It should not be called anywhere else. This function registers a
custom exit (a custom function pointer) for a given USER_ exit function:
int CUSTOM_register_exit ( const char* context,
const char* base_ftn_name, /* <I> */
CUSTOM_EXIT_ftn_t custom_ftn /* <I> */
);

/* <I> */

context
Specifies the context in which this custom exit has to be registered. It is the
name of the customization library (for example, GM, Ford, Suzuki).

base_ftn_name
Specifies the name of the USER_ exit for which the custom exit must be
registered (for example, USER_new_dataset_name).

custom_ftn
Specifies the name of the custom exit (a custom function pointer).

CUSTOM_execute_callbacks
This function executes the custom callbacks registered for a particular USER_ exit:
int CUSTOM_execute_callbacks ( int* decision, /* <O> */
const char* ftn_name, /* <I> */
variables
/* <I> */
);

decision
Executes one of the following options:

ALL_CUSTOMIZATIONS

ONLY_CURRENT_CUSTOMIZATION

NO_CUSTOMIZATIONS

ftn_name
Name of the USER_ exit.

4-26

Server Customization Programmers Guide

PLM00074 J

ITK customization

variables
The variables that need to be passed to the custom exit (a custom function
pointer).

For each custom library registered in the Options dialog box, accessed from the
Edit menu in My Teamcenter:

Get the corresponding custom function pointer.

Execute the custom function with the arguments passed.

This function is called in all the USER_ functions in user exits and server exits. The
va_list list must be expanded in the custom function.
CUSTOM_execute_callbacks_from_library
This function executes custom callbacks registered in a particular library for a
particular USER_ exit by:

Getting the corresponding custom function pointer.

Executing the custom function with the arguments passed.

int CUSTOM_execute_callbacks_from_library ( int* decision, /* <O> */
const char* lib_name, /* <I> */
const char* ftn_name, /* <I> */
variables
/* <I> */
);

decision
Executes one of the following options:

ALL_CUSTOMIZATIONS

ONLY_CURRENT_CUSTOMIZATION

NO_CUSTOMIZATIONS

lib_name
Specifies the name of the customization context.

ftn_name
Specifies the name of the USER_ exit.

variables
Specifies the variables that need to be passed to the custom exit (a custom
function pointer).

The va_list list must be explained in the custom function.

Example
The following code (using cust1 as the site) shows registering a custom handler
in a custom exit:
extern int cust1_action_handler(EPM_action_message_t msg) {

PLM00074 J

Server Customization Programmers Guide

4-27

Chapter 4

ITK customization

/* insert custom handler code here */

}
extern DLLAPI int cust1_register_custom_handlers(int *decision, va_list args) {
int rcode = ITK_ok;
*decision = ALL_CUSTOMIZATIONS;
rcode = EPM_register_action_handler("cust1-action-handler", "",
cust1_action_handler);
if (rcode == ITK_ok)
fprintf(stdout, "cust1-action-handler successfully registered!\n");
else
fprintf(stdout, "WARNING - cust1-action-handler NOT registered!\n");
return rcode;
}
extern DLLAPI int cust1_register_callbacks () {
CUSTOM_register_exit ( "cust1", "USER_gs_shell_init_module",
(CUSTOM_EXIT_ftn_t) cust1_register_custom_handlers);
return ( ITK_ok );
}

Register run-time properties using custom hooks

There is a limitation on registering property methods on the same type. Among the
registered property methods on the same type, the top one in the preferences stored
in the database overrides the registration of the one that follows. Therefore only
one registration works.
To work around this, register multiple methods (one as base method and the rest as
post_action methods) on the same type by following these steps:
1. Register one property method as base method, and the rest as post_action
methods.
2. To register the property methods, follow this sample registration in the following
code:
USER_prop_init_entry_t icsTypesMethods[] =
{
{ (char *)"WorkspaceObject", icsInitWorkspaceObjectProperties, NULL
}
};
int npTypes = sizeof ( icsTypesMethods )/sizeof( USER_prop_init_entry_t );
for ( i = 0; i < npTypes; i++ )
{
// firstly, findout if a base method is already registered for
// TCTYPE_init_user_props_msg
ifail = METHOD__find_method( icsTypesMethods[i].type_name,
TCTYPE_init_user_props_msg, &initUserPropsMethod );
if( ifail == ITK_ok)
{
if ( initUserPropsMethod.id != 0 )
{
// already registered, the add the method as a post_action method
// add method as post action to the existing base method
ifail = METHOD_add_action( initUserPropsMethod,
METHOD_post_action_type,
icsTypesMethods[i].user_method,
icsTypesMethods[i].user_args );
}
else
{
// not yet registerd, add the method as a base method
// there is no method registerd
ifail = METHOD_register_method ( icsTypesMethods[i].type_name,

4-28

Server Customization Programmers Guide

PLM00074 J

ITK customization

TCTYPE_init_user_props_msg,
icsTypesMethods[i].user_method,
icsTypesMethods[i].user_args,
&methodld );
}
}
}

Core functions
The core functions and classes are the basic building blocks of Teamcenters
functionality.

File relocation
When you create a dataset in Teamcenter, a file is created in the users volume
directory. Once it is released (in other words, signoff is performed), it remains in the
same volume along with other non-released objects. To list and backup all of the files
related to the released datasets for all of the users, all of the dataset files should be
copied to a separate directory.
Two programs have been developed to perform this task. One activates an action
handler to relocate the files on release of the job. The other relocates all of the
existing released jobs.
Relocating datasets
To relocate a dataset after it is released, you need to register an EPM action handler
with the EPM_register_action_handler function. Input parameters should be
action strings and function callbacks.
A handler is a small program used to accomplish a specific task. There are two
kinds of handlers:

Rule

Action

Note

This function should be called in the user_gsshell.c file.

Add an action handler

1. Run Teamcenter and log on as a system administrator.
2. Open Workflow Designer.
3. Choose FileNew Root Template.
The New Root Template dialog box is displayed.
4. Give the new root template a name and select another root template to base
this template on. Click OK.
5. Click the button that displays the task handlers pane.

PLM00074 J

Server Customization Programmers Guide

4-29

Chapter 4

ITK customization

6. Select the task action where you want the handler to execute, and then select
the handler.
7. Select the arguments needed for your handler and type their values.
8. Click the plus button
to add the handler to the task action. When you are
done, close the Handlers dialog box.
Note

To incorporate the action handler into other release procedures, follow steps
3 through 8.

Sample programs
The following sample programs relocate files associated with datasets being released.
It assumes that the FLRELDIR directory exists on the operating system. If any of
the target objects are datasets, all files referenced by it are copied to the operating
system directory specified by FLRELDIR.
It is assumed, for these examples, that the usr/tmp/release directory exists on the
system and that all users have write permission to that directory.
Note

These functions relocate only the files associated with the dataset. If the job
is released for an item, folder, form and dataset, then this function only
relocates the files for the job released for the dataset.

smp_cr_mv_hl.c
The smp_cr_mv_hl.c file contains the USER_cr_init_module function. This
should be called in the USER_gs_shell_init_module function.
Once called, a new SMP-auto-relocate-file action handler is registered and the
job is released. If it contains a dataset, the dataset is relocated to the FLRELDIR
directory.
smp_cr_mv_fl.c
This file contains the relocate_released_dataset_file function. Its purpose is
to relocate files associated with the datasets being released. Using the tag of the
release job as input, it finds all target objects. If any of the target objects is a dataset,
all files referenced by it are copied to the operating system directory specified by
FLRELDIR. The directory is not created by this function.
Compile and execute smp_cr_mv_hl.c and smp_cr_mv_fl.c
To compile the above files, add the USER_cr_init_module function to the
USER_gs_shell_init_module function of the user_gsshell.c file (supplied by
Teamcenter). Compile the smp_cr_mv_hl.c, smp_cr_mv_fl.c and user_gsshell.c
files separately. Create a new libuser_exits.sl file using the above .o files.
To execute this file, add the SMP-auto-relocate-file action handler to all of the
release procedures. Once the job is released, it copies released datasets to the
FLRELDIR operating system directory.

4-30

Server Customization Programmers Guide

PLM00074 J

ITK customization

sample_cr_move_files_main.c
The sample_cr_move_files_main.c file works as a stand alone ITK program. It
logs into Teamcenter and initializes the AE, PSM and SA modules. Next, it creates
the FLRELDIR operating system directory. It then searches for all released jobs
containing datasets and relocates these dataset files to the FLRELDIR directory.
Compile and execute sample_cr_move_files_main.c and smp_cr_mv_fl.c
Compile the sample_cr_move_files_main.c and smp_cr_mv_fl.c files
separately. Link the two files using the linkitk command and create the
sample_cr_move_files_main executable. You can execute this file from the
command line using:
sample_cr_move_files_main -u=user-id -p=password -g=group

The user-id variable is the Teamcenter user name; password is the Teamcenter user
password; and group is the Teamcenter user group name.

Change the revisioning scheme

If you want to change the default item revisioning scheme to something else (for
example, revisions A, B, C, and so forth to revisions -a, -b, -c, and so on), you can
modify the sample code in the user_part_no.c file.
Performing this type of customization is only required if you have overly complex
revision scheme that cannot be done in the Business Modeler IDE using naming
rules or revision naming rules.
For more information about creating naming rules using the Business Modeler IDE,
see the Business Modeler IDE Guide.

General hints about property coding

When you customize properties using ITK, pay attention to aspects of the coding
such as allocating memory, use of messages, and caching values. Careful use of these
areas yields a better implementation.
Memory allocation
There are two memory allocation calls:

MEM_alloc

MEM_alloc_persistent

The difference between the two is that there is a function that will free all
MEM_alloc space allocated since a given point which can be used as a simplistic
form of garbage collection. The only place where this is used is inside POM functions
which free all MEM_alloc space that was allocated from inside the function as it
returns. For normal use, it makes no difference which allocation function you use,
but if you are writing code that might be called from a POM callback (such as an
Access Manager-registered function) then you should use MEM_alloc_persistent if
you want your memory to persist, and MEM_alloc if you intend to free it on exit. If
you forget to free it, the POM function will free it by garbage collection on exit.

PLM00074 J

Server Customization Programmers Guide

4-31

ITK customization

Chapter 4

Method arguments
Method arguments extracted using va_arg must be extracted in the sequence
indicated in the Integration Toolkit Function Reference. For example:
tag_t prop_tag = va_args(args, tag_t);
char **value = va_args(args, char**);
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Messages
The following messages are used to set property values:

PROP_init_value_msg

PROP_ask_value_type_msg

PROP_set_value_type_msg

PROP_init_value_msg
The PROP_init_value_msg function initializes a property with a specified value.
Caution

A method registered against this message does not exist for most objects.
Therefore the METHOD_find_method, METHOD_add_action, and
some other functions cannot be used unless another method is registered.
The METHOD_find_method function does not consider this an error
and does not return a failure code. It merely returns a null method_id.

PROP_ask_value_type_msg
The PROP_ask_value_type_msg function can be used to return the value of a
property.
Note

Caution

This message is called by most ITK functions and internally by Teamcenter.

However, some ITK functions (for example, Form, FL, AE, and so on) may
be bypassing this code at this time.
Never call the PROP_ask_value_type function from inside a method
registered against the PROP_ask_value_type_msg function on the
same property. This forces Teamcenter into a recursive loop. Instead use
the PROP_get_value_type function to get the raw data value.

PROP_set_value_type_msg
The PROP_set_value_type_msg function is passed whenever the user chooses OK
or Apply in the Attributes dialog box or sets a value in the workspace, Structure
Manager, or with ITK. The PROP_assign_value_type function can be used.
Caution

4-32

Never call the PROP_set_value_type function from inside a method

registered against the PROP_set_value_type_msg function on the same
property. This forces Teamcenter into a recursive loop. Instead use the
PROP_assign_value_type function to store the raw data value.

Server Customization Programmers Guide

PLM00074 J

ITK customization

Value caching
Value caching is a technique used with run-time properties to improve performance.
This is valuable when the value of a derived property is not likely to change during
the current Teamcenter session. To cache values, use the following technique:
1. The first time a run-time property is called using the PROP_ask_value_string
method, cache the string value with the PROP_assign_type method.
2. On subsequent PROP_ask_value_string method calls, use the cached value by
calling the PROP_get_type method.

Persistent Object Manager layer

You can use ITK to customize the Persistent Object Manager (POM), POM
inheritance, and the POM enquiry module.

Persistent Object Manager

The Persistent Object Manager (POM) forms part of the data management layer of
the ITK. POM provides the interface between Teamcenter objects and the relational
database management system (RDBMS). POM provides:

Data manipulation services

Manipulation of in-memory objects and support for their saving and retrieval
to and from the underlying RDBMS.

Locking
Support for many different applications accessing the same data concurrently.

Referential integrity
Protection against the deletion of data used by more than one application.

Access controls
Support for the access control lists attributed to objects. The access controls
themselves are manipulated by functions provided by the Access Manager.

Concepts
To understand how the POM works, you need to know about classes, attributes,
instances, indexes, and tags.
Class
A class is a definition of a data structure containing one or more attributes. Classes
are organized in hierarchy, with superclasses and subclasses. A class inherits
attributes from its parent (superclass) and passes its attributes on to its children.
POM allows only single inheritance; that is, any class can have only one parent, one
grandparent, and so on.

PLM00074 J

Server Customization Programmers Guide

4-33

Chapter 4

ITK customization

In the following figure, classes B and C can inherit from (in other words, be direct
subclasses of) only one immediate superclass, class A. Classes B and C cannot also
inherit from class XX.

Classes
Each class has a unique name. For example, the Human class is a subclass of
Primate, which is itself a subclass of Mammal. Primate inherits attributes such
as hairiness and warmbloodedness from the definition of Mammal. In addition
to the inherited attributes, it adds its own, such as binocular vision. As Human
inherits from Primate, it therefore has all the attributes of a Primate. In addition,
it can have specific attributes, such as I.Q.
Attribute
Attributes are the individual data fields within classes. Each attribute has a unique
name within the class that identifies it. It also has a definition that defines the
type of data object and its permitted values. For example, a Human has attributes
of weight and eye color. Weight is a real number. Eye color may be one of a set
(for example, blue, grey, brown).
You can declare attributes to be class variables. This is an attribute that has the
same value for all instances of the class. When the attribute value is changed by
modifying any instances, the value changes for all instances of the same class (or
subclass). This is also known as a static variable.
Instance
Instances are the individual data items created from class definitions. Making an
instance from a class definition is instantiating that class. Each instance has the
attributes defined in the class, but has its own values for these attributes. For
example, an individual Human might have a weight value of 160 pounds and an
eye color value of brown.
Some classes are defined to be uninstantiable, meaning they cannot be instantiated.
An example of such a class would be Mammal.
Index
Indexes are created on one or more of the attributes that exist within a class
definition. Indexes can only be defined across attributes that belong to the same
class.
Indexes aid performance. For example, two attributes that the Human class has
are weight and eye color. To list all Humans who have an eye color of brown, you
would probably search the database for all instances of the Human class that
matches the applied criteria.

4-34

Server Customization Programmers Guide

PLM00074 J

ITK customization

Though this type of search is performed well by a RDBMS, it is slow. The alternative
is to have an index on the eye color attribute. Internally, the database maintains its
index of where to find objects with the required attributes. Therefore, the search for
Humans with brown eyes is much faster if an index is put on a value attribute.
To optimize performance when defining the indexes, you have to anticipate what
searches the application is likely to be required.
Note

Indexes improves query performance when searching on that indexed

attribute, but at a small time penalty for save, update, and delete operations
which must update the instance and the index.

An index can be defined as unique. This ensures that the POM checks for an existing
value for an index when a class with attributes containing an index is instantiated.
The uniqueness is tested only upon a save to the database. While an instance
remains in a users session, duplicates may exist.
For example, the POM_user class has a name attribute that has a unique index
defined on it. This prevents two POM users with the same name from being
registered with the POM.
When the unique index spans more than one attribute, the uniqueness must be for
all the attributes combined. For example, the POM_user class with first_name
and second_name attributes, both covered with a unique index, allows (John Smith
and John Brown) and (John Smith and Bill Smith), but not (John Smith and John
Smith), to be registered with POM.
Tag
A tag is a short-lived reference to an instance. The tag persists for the length of a
session and can be exchanged between processes in a session.
To exchange a reference to an instance between processes of different sessions, the
tag must be converted to a persistent identifier called a handle by the sender, and
from handle to tag by the receiver. The receivers tag can be different in value to the
senders as they are in different sessions.
Data manipulation services
The data manipulation services allow you to execute various actions on instances.
Note

Do not use these methods on WorkspaceObject business objects. Only use

these methods if a more specific function is not available.

Create instance
The POM_create_instance function allows you to create an instance of a specified
class.
Caution

Only use this method when you cannot use the

Teamcenter::BusinessObject::create(Teamcenter::CreateInput*)?
method.

You can start the POM module without setting a current group. Because of this, it is
also possible that an attempt can be made to create an instance for which an owning
group cannot be set. When this happens, the function fails with no current group.

PLM00074 J

Server Customization Programmers Guide

4-35

ITK customization

Chapter 4

A function fails with an improperly defined class when the class is only partially
defined. For example, if you define an attribute to have a lower bound but have not
yet set the value for this lower bound.
When an instance is created, all attributes with an initial value defined are set to
that value. System-maintained attributes, such as creation date and owning user,
are set by the system. All other attributes are empty. These must be set to allowable
values before the instance can be saved.
Copy instances
To create copies of a set of existing instances, which must be loaded in the current
session, use the POM_copy_instances function. The new instances are of the same
class as the source. The attributes are maintained as follows:

Application-maintained attribute values are copied.

System-maintained attribute values (for example, creation_date) are set

appropriately.

The copy is created as an instance of the class in which the original instance was
instantiated. This applies even if the original instance is loaded as an instance of
a superclass.
Save instances
By using the POM_save_instances function, instances created, or changes that
were made to a set of instances, are saved to the database. An additional option of
this function is the ability to discard the in-memory representation.
The POM_save_required function checks whether a specified instance was
modified. The instance may be newly created or loaded for modification in the
callers local memory storage. The function determines modification by testing
whether the local memory representation of the instance was altered since the
instance was loaded.
After an object instance is saved, it remains locked. The application must unlock the
object by calling the POM_refresh_instances function.
Load instances
Instances can be loaded as instances of their own class.
The POM_load_instances function loads and creates complete instances
of a class. To load instances that are of different classes, use the
POM_load_instances_any_class function. However, the class that they are loaded
as must be common to all loaded instances as in the following figure.

4-36

Server Customization Programmers Guide

PLM00074 J

ITK customization

Class hierarchy
When the modify_lock argument for this function is set, the instances are locked
for modification, therefore no other session can lock them for further modification
at the same time. When they are not locked for modification but are either set to
read_lock or no_lock, this permits other sessions to lock them for modification or
read as required.
The POM_load_instances_by_enq function executes a specified enquiry and loads
the resulting set of instances from the database, creating in-memory copies of the
instances.
The POM_is_loaded function checks whether a specified instance is loaded in the
callers local memory. Newly created instances are counted as loaded, as they are
already present in the local memory having been created during that session.
To check whether the given instance is loaded in the callers local memory for
modification, use the POM_modifiable function.
Unload instance
The POM_unload_instances function unloads specified instances from the
in-memory representation without saving any changes that were made to the
in-memory representation.
To save changes that were made to the in-memory representation, use the
POM_save_instances function.
Refresh instances
The refresh operation is the equivalent to unloading and then reloading an instance
without having to complete the two separate operations. This operation causes the
attribute values to be refreshed to the corresponding values in the database.
Occasions when the refresh operation can be used are:

When you need to update the instance that is currently being worked on to
reflect changes that may have occurred since the users copy was made.

When you decide to scrap all changes that have been made to the instance.

The POM_refresh_instances function refreshes a specified set of instances when

instances are all of the same class.
To refresh a specified set of instances that are not all of the same class, use the
POM_refresh_instances_any_class function. The instances are refreshed in
their actual class.

PLM00074 J

Server Customization Programmers Guide

4-37

ITK customization

Chapter 4

These refresh functions allow the specified instances locks to be changed.

The POM_refresh_required function checks whether a specified instance, which
is loaded for read in the callers local memory, requires a refresh by testing if the
database representation of the instance has been altered.
Delete instances
The POM_delete_instances function enables the deletion of a specified instance.
The POM_delete_instances_by_enq function enables the execution of a specified
enquiry followed by the deletion of the resulting instances from the database.
Note

The instances to be deleted must not be referenced or loaded by this or any

other POM session. This is how the POM maintains referential integrity.
Newly created instances (in other words, those that have not yet been saved)
cannot be deleted. This is because deletion is a database operation and these
newly, unsaved instances do not yet exist there. Unloading these instances
effectively deletes them. If a class is application-protected, then instances
of that class can only be deleted by that application (for more information,
see Application protection).

Order instance
To order an array of loaded POM instances on the values of attributes that are
common to all the instances, use the POM_order_instances function.
For this operation to be successful, the following criteria must be applied:

The instances must be loaded.

Only one attribute may be specified for ordering.

None of the attributes being ordered can be empty.

Reference of instance
The POM_references_of_instance function enables you to find all instances and
classes in the database which contain references to a specified instance.
The level of the search through the database is determined by the n_levels
argument. The where_to_search argument determines which domain to search (in
other words, local memory, database or both).
The DS argument limits the search to the working session (things not yet committed
to the database). The DB argument limits the search to the database only. DS and
DB together extends the search to both domains.
When a class is found to be referencing an instance, there is a class variable which
contains that reference.
Instances of class
The POM_instances_of_class function returns all the instances of a specified class.

4-38

Server Customization Programmers Guide

PLM00074 J

ITK customization

Class of instances
To find the class to which an instance belongs, use the POM_class_of_instance
function. This function returns the class in which the instance was instantiated.
Use the POM_loaded_class_of_instance function to find the class of an instance
as it has been loaded.
Inquiries to find instances
An inquiry to the POM is a pattern that can be applied to saved instances of a
specified class (and its subclasses) to select a subset of those instances.
The inquiry takes the form of restrictions on attribute values and combinations of
the same, using the logical operators AND and OR. For example, if you have a
furniture class with a color attribute and a table subclass with a height attribute, it
is possible to create an inquiry to list all instances of the table class that has the
restriction that the color is red.
Once an inquiry is created, it can be combined with other inquiries (such
as height less than three feet). It can then either be executed (to return a
list of tags of those instances that match the inquiry) or it can be passed to
the POM_load_instances_by_enq, POM_select_instances_by_enq, and
POM_delete_instances_by_enq functions which then load, select, or delete, as
appropriate, those instances which satisfy the inquiry.
The following functions enable the user to create, but not to execute, an inquiry of a
specified attribute or array-valued attributes:

POM_create_enquiry_on_type

POM_create_enquiry_on_types

To execute a specified inquiry and return a list of tags of instances as specified by

the inquiry, use the POM_execute_enquiry function.
To combine two inquiries use the POM_combine_enquiries function.
The POM_order_enquiry function specifies the order in which to produce the
instances.

Each attribute may be ordered in ascending or descending order. The instances

are ordered on the value of each attribute in turn, starting with the first
attribute in the array.

This function can be used to override a previously specified order. Therefore, for
instances, the same enquiry_id can be used more than once to produce different
orderings of the same instances.

Note

It is not possible to order on either variable length arrays (VLA) or arrays.

The POM_negate_enquiry function negates a specified enquiry and the

POM_delete_enquiries function deletes specified enquiries.

PLM00074 J

Server Customization Programmers Guide

4-39

ITK customization

Chapter 4

Attribute manipulation
Attribute manipulation enables you to modify attributes in the database, set and get
attributes of loaded instances, manipulate tag and class IDs, manipulate variable
length arrays, and check references.
Note

Use these methods only if you must manage attributes outside the scope
of a business object.

Modifying attributes in the database

The following group of functions enables you to change the attribute values of an
instance without first loading the instance:

POM_modify_type

POM_modify_types

POM_modify_null

POM_modify_nulls

POM_modify_type_by_enq

POM_modify_types_by_enq

POM_modify_null_by_enq

POM_modify_nulls_by_enq

You can change the following attribute values:

A specified attribute to a given value or to NULL for specified instances all

in the same class.

All or some of the specified array-valued attribute to the given array of values, or
to NULL, for specified instances in the same class.

The specified attribute to the given value for all instances found by an enquiry.

All or some of the specified array-valued attributes to the given array of values
for all instances found by an enquiry.

These functions modify data directly in the database and not on loaded instances.
Setting attributes of loaded instances
The following functions enable the user to set the value of a specified attribute in
an instance:

4-40

The POM_set_attr_type and POM_set_attr_null functions change the

specified attribute to the specified value or to NULL in the local memory only, for
instances when the specified instances are all in the same class.

The POM_set_attr_types and POM_set_attr_nulls functions change all or

some of the specified array valued attribute to the specified array of values or to
NULL, in the local memory only, for instances all in the same class.

Server Customization Programmers Guide

PLM00074 J

ITK customization

When changing the specified array-valued attribute to NULL, the attribute must
exist for all the instances, therefore there must be a class with that attribute and
instances must be in that class or in a subclass of it. This also applies to nonarray
attributes.
Getting attributes of loaded instances
You can use the following functions within the POM module to retrieve the value of a
specified attribute in an instance, for loaded instances only:

POM_ask_attr_type
Returns the value of the attribute for a specified instance. The value returned
is the value of that instance in the local memory; this could differ from the
corresponding value in the database.

POM_ask_attr_types
Returns n-values of values of the array-valued attribute for a specified instance
starting from the position start. The values returned are those of the value of
that instance in the local memory; these could differ from the corresponding
values in the database.

Tag, class_id, and attr_id manipulation

The POM provides the following functions for conversion and comparison operations:

POM_tag_to_string

POM_string_to_tag

POM_compare_dates

Variable length array manipulation

Variable length arrays (VLA) are attributes that can have a variable number of
elements of their declared type. The data type of the VLA and class type (for typed
references) or string length (for notes and strings) are declared when the attribute is
defined.
When an instance of a class with a VLA attribute is created, that VLA attribute
is initialized to a zero length.
The following functions are used to extend or remove elements from the VLA. All
these functions, with the exception of POM_reorder_attr because it can be applied
to any array, are specific to VLAs:

POM_insert_attr_types
Inserts the specified values into a specified VLA attribute at a specified position.
The maximum value for the specified position is the length of the VLA.

POM_clear_attr
Clears all values from the specified VLA, effectively setting its length to 0 (zero).

POM_remove_from_attr
Removes a specified number of elements from the VLA.

PLM00074 J

Server Customization Programmers Guide

4-41

ITK customization

Chapter 4

POM_append_attr_types
Adds the specified values to the end of the specified VLAs.

POM_length_of_attr
Returns the length of a specified VLA (in other words, the number of values
in the VLA).

POM_reorder_attr
Reorders elements within a VLA.

Check reference
To perform reference checking to find the type of a specified attribute of an instance,
use the POM_check_reference function.
The POM_check_reference function permits checking for consistency between the
class definition and the instance information.
Users and groups
The POM allows users who may be members of one or more groups. Users,
groups, and members are maintained internally by instances of the POM_user,
POM_group, and POM_member classes. A user is associated with a group by the
existence of a member instance that links the user to the group. These instances
must be saved to the database (with the POM_save_instances function) before
they become usable.
A specified member of a group has the privilege of being the group administrator.
This empowers that user to add or remove other members to or from that group. The
system administrator or any member of the system administrator group has this
privilege for any group.
Users and groups in the POM are objects in a protected application, the individual
instances can only be manipulated by the authorized application (see the
POM_register_application and POM_identify_application functions). System
administrators that have been called to perform the changes can create new users
and delete old users.
Note

If you create a new member object for yourself, you cannot immediately set
your current group (using the POM_set_group function) to that specified.
You must save the member object first.

User, group and member objects are instances of application-protected classes,

though some of the attributes of these instances are declared to be public read so
that they can be asked about using the normal calls. The effect of making these
classes application protected is to restrict access to certain attributes (for example,
changing the password of a user is only possible by someone who knows the old
password) or an system administrator and to prevent every user of the system from
being able to generate new users or delete bona fide users.
Create
The following functions create instances of users, groups, and members:

4-42

Server Customization Programmers Guide

PLM00074 J

ITK customization

POM_new_user

POM_new_group

POM_new_member

The group administrator of the group in which the member resides, as well as the
system administrator, can create members of a group.
Users must be associated with a group using the member functions before the user
and group become registered.
Initialize
The following functions initialize users, groups, and members:

POM_init_user

POM_init_group

POM_init_member

Only system administrators are allowed to use the these functions.

If a new instance of the POM_user class is created, using the POM_new_user
function, the attributes of the instance are automatically initialized. However, if an
system administrator creates a subclass of the POM_user class, the attributes (for
example, names, password, and so on) of any new instance of the subclass must be
initialized. Call the POM_init_user function to perform this initialization.
The same rules apply to creating groups and members.
Delete
The following functions delete users, groups and members:

POM_delete_user

POM_delete_group

POM_delete_member

These functions are required because of the application protection. They take
tags of instances of groups, users or members as appropriate or any subclass of
the same. If the subclass is also application protected, then that application must
also be identified.
Only a system administrator can use these functions.
Note

When a user logs into the POM, the appropriate user and group objects
are locked so that they cannot be deleted. This lock is updated whenever
the user changes the group.

After a member object is deleted, the user specified cannot log onto the listed group.

PLM00074 J

Server Customization Programmers Guide

4-43

ITK customization

Chapter 4

Set group
To set the group to the named group, use the POM_set_group function.
Alternatively, the POM_set_group_name function sets a specified name for a
specified group.
The POM_set_default_group function sets the default group for the current user.
The user object must be loaded for modification and then must be saved again
afterwards for this change to be permanent.
The POM_set_user_default_group function sets the tag of the specified users
default group. This is the group which the user is logged into if the POM_start
function is given an empty string for the group_name argument. Only a system
administrator or that individual user can use this function.
To enable a user that is logging into a group to have group system administrator
privileges, use the POM_set_group_privilege function with the privilege
value of 1. A privilege value of 0 (zero) ensures that a person logging into the
specified group only has the privileges associated with an ordinary user. The
POM_set_member_is_ga function sets the group administration attribute for the
specified group to the specified value, either 0 (zero) or 1.
A member is a loaded form of the database link that gives the user authority to log
onto the chosen group (in other words, gives the user membership to the group).
The POM_set_member_user function sets the user (tag) attribute of the specified
member instance to the supplied user tag. The POM_set_member_group function
sets the group (tag) attribute of the specified member instance to the supplied
group tag.
Set user status and license level
The POM_set_user_status function sets the status of the user. If the user is not
active, set the new_status argument to 1; if the user is active, set it to 0. Only the
system administrator can use this function. The status is not interpreted by the
POM, it is provided for the system administrator to classify users.
The POM_set_user_license_status function sets the license level of the user. This
function displays the number of licenses purchased and the number in use.
User and group inquiries

4-44

The POM_ask_owner function returns the owning user_tag and group_tag

for an instance.

POM_is_user_sa advises if the current user is logged into the POM under a
privileged group.

POM_ask_default_group returns the tag for the default group of the current
user.

In contrast to the previous function, the POM_ask_user_default_group

function returns the currently set default group for a user. Only a system
administrator or the individual user can use this function. The user object must
be loaded before using these functions.

Server Customization Programmers Guide

PLM00074 J

ITK customization

The POM_ask_group function returns the name of the group, as handed to the
POM_set_group or POM_start functions, and the group_tag, as returned by
the POM_set_group function.

The POM_get_user function returns the name of the logged in user, as handed
to the POM_start function, and the user_tag, as returned by the POM_start
function.

Application protection
Classes can be associated with a particular application, so that only that application
can perform the following operations on instances of these classes:

Set

Ask

Delete

The following operations are not affected by application protection:

Create
The instance is of no use unless the attribute is completed, and it is not possible
to do this without using set.

Load
Ask is required to get at the information.

Save
This fails if there are any empty attributes, and set is required to fill them in.

Modify
Modify is the equivalent to load, set, save, and unload.

The application protection affects all attributes defined in the given class in all
instances of it or its subclasses. Attributes can be unprotected by declaring them as
public, read, or modify in the attribute definition descriptor.
The association between a class and an application is not inherited by subclasses of
the class. Those subclasses may have an association with some applications. This
could be the same one as the class itself.
The POM_identify_application function is used by an application to identify itself
to the POM so that the POM allows it to perform protected operations on classes
with which the application is associated. On completion of the protected operations,
the application becomes anonymous. POM does not allow further operations without
the application re-identifying itself.
For an application to be registered with POM and thereby obtain the application
ID and code that is required by the POM_identify_application function, use the
POM_register_application function.
The code number returned by the POM_register_application function is a random
number which, in turn, is used as a level of security checking.

PLM00074 J

Server Customization Programmers Guide

4-45

Chapter 4

ITK customization

System utilities
System utilities are managed by POM functions that enable you to start and stop
the POM, manipulate passwords, rollback a process to a previous state, control
time-outs and logons, and trap POM errors.
Starting and stopping POM
The POM_start function is the first call to the POM module and therefore it logs
the user into the POM. If you call any other function before this function, then that
function fails except for POM_explain_last_error which always works.
To log out of the POM, use the POM_stop function.
Password manipulation
To set the password for the specified user, use the POM_set_password function.
Note

Because of the severity of this operation, it can only work on one user at
a time.

The POM_check_password function checks the password for a user by comparing

the given password with the stored password.
For security, the stored password is encrypted and never decrypted or returned
through the interface. The encryption algorithm is not public.
Note

When Security Services are installed and the TC_SSO_SERVICE

environment variable is set in the tc_profilevars file, passwords
are managed by an external identity service provider rather than
Teamcenter. In this case, the POM_set_password function returns
POM_op_not_supported (the ability to change a password in the rich
client and ITK is disabled).

Rollback
The rollback facility enables you to restore a process to a previous state. The state at
which a process is restored is dependent on the position of the specified markpoint.
Markpoints are used at your discretion and are placed using the
POM_place_markpoint function. When a markpoint is placed, an argument is
returned advising you of the identifying number of that markpoint.
To rollback to an earlier state in the process, use the POM_roll_to_markpoint
function specifying the markpoint to which you want to rollback. This function
restores the local memory and the database to the corresponding state that it was in
when the specified markpoint was set.
As an overhead saving, rollback can be turned off with the POM_set_env_info
function.
The rollback removes the callers changes to the database. Any changes to the
database by other users are unaffected. If other users have made changes which
prevent the callers changes being reversed (for example, deleted or changed values
in an instance in the database), then the rollback fails.

4-46

Server Customization Programmers Guide

PLM00074 J

ITK customization

Time-outs
You can use the POM_set_timeout function to set a session wide time-out value
to determine the period during which a POM function repeatedly tries to lock an
instance for change (for example, when calling the POM_load_instances function).
After the time-out period, if the POM function that is to perform the change is
unsuccessful at getting the lock, it returns the appropriate failure argument as
described in the relevant function.
The POM_ask_timeout function advises the user what time-out period has been
set for the session in seconds.
Errors
In the event of a failure, the POM_explain_last_error function explains why the
last failing POM function failed. The information that is returned by this function
includes:

The actual error code.

The argument that caused the function to fail.

The name of the function that failed.

A description of what that particular error code means.

The POM_describe_error function returns a string describing the specified error

code.
The description returned by this function is the same as that returned by
POM_explain_last_error. For convenience the POM_describe_error function
can be called with any error code at any time.
Control of logons
The control of logons, which allows or prevents other users from accessing POM, is
set by the POM_set_logins function. When the system administrator needs to
perform an operation that requires only one POM user, the system administrator
can use the POM_set_logins function to prevent any other user from logging into
the POM. In the unusual event of the process which disabled logons terminating
abnormally, the system administrator does have the authority to log on using the
appropriate group and password as identification, thus overriding the effect of the
earlier POM_set_logins function call.
However, all POM users can use the POM_ask_logins function to determine
whether other users are currently allowed to access the POM.
Environmental information
The POM_set_env_info function offers alternative methods of enabling and
disabling operations as explained in its description. This function sets the following
environmental information:

PLM00074 J

Enable or disable rollback.

Server Customization Programmers Guide

4-47

ITK customization

Chapter 4

Enable or disable attribute value checking in the local memory (for example, for
the duplication of unique attributes or for checking against upper/lower bounds).

Enable or disable journalling (for example, for writing a functions arguments to

the system log when debugging and bug reporting).

Enable or disable argument checking.

Log on of a traceback to the log file when receiving an error.

Writing of all of POM SQL to the log file.

The POM_ask_env_info function returns the environmental information that was

specified by the POM_set_env_info function.
Miscellaneous
There are several POM functions that give you access to SQL statements and
provide user assistance.
SQL
The application data stored by the POM module is accessible using direct SQL
statements for read and write purposes. The POM_sql_view_of_class function
creates a database view of the selected attributes in the given class. The view is
given the name supplied and the columns are aliased with the column names that
are given in the argument for the column names.
The attributes can be from a specified class or any superclass, but they cannot
include any array types.
Direct SQL access to the internal structure
These functions have been provided to allow the end user access to the database
tables used by the POM:

The POM_dbname_of_att function takes a class identifier and an attribute

identifier and returns the textual names of the SQL database table and the
column within that table in which the relevant attribute is stored. This function
can be used to either directly access the values of a specified attribute for
specific instances or to produce a query over all values of the relevant attribute
in a given class.

The POM_type_of_att function returns the array type of the attribute identified
by its class_id and attr_id. The returned types of arrays are:

4-48

Nonarray (for example, an integer)

Small array

Large array

Variable length array

The POM_tag_to_uid function returns a UID, which is an internal reference to

an instance.

Server Customization Programmers Guide

PLM00074 J

ITK customization

Other functions available for user assistance

Because some POM tables (in other words, those that hold the values for the class
variables) have the entries specified by a combination of the site identifier, internal
attribute, and class identifiers, you must use the following functions:

POM_site_id
Returns the site ID of the local POM installation.

POM_attr_to_apid
Converts the external class and attribute identifiers into the internal integer
attribute identifier.

POM_class_to_cpid
Converts the external class identifier into the internal integer representation
for a class.

POM_get_char_ordering
Returns the ordering on the character set in use. This is useful when creating an
enquiry which selects on a string-valued attribute.

POM_describe_token
Returns a string describing the specified token (for example, for the POM_int
token, which is a defined value, the returned string might be integer).

POM_free
Calls MEM_free. Frees the space that the POM allocated internally when
returning an array of information.

Values that can be handed to this function are indicated by the letters <OF> after
the argument in the function syntax.

POM enquiry module

With the POM enquiry system, you can ask the database directly for information
instead of navigating loaded objects. For example, you can request a list of all the
workspace objects where the object_name is test. Another example is a list of all
the instances of a class that have a reference to a particular tag. If you use normal
ITK objects to try to get this information, it takes a lot of time and memory. The
POM enquiry system gives you this information much more quickly and efficiently.
The enquiry system allows you to develop queries that conform to the SQL-92
standard with a few exceptions. These exceptions are:

You cannot use SELECT * FROM. Only named attributes are allowed.

You cannot use Cartesian products.

You cannot use outer joins.

Note

PLM00074 J

POM enquiries are not the same as saved queries. They are completely
different mechanisms.

Server Customization Programmers Guide

4-49

ITK customization

Chapter 4

Differences between old and new systems

There are actually two different enquiry systemsa newer one and an older one. You
should use the newer one with the calls that begin with POM_enquiry_ because:

It produces better, more efficient SQL which runs faster.

It supports more features present in SQL and allows you to do more complex
queries.

You can ask for more than one attribute to be returned. The old system only
returned the tags of matching objects.

You can call the POM_load_instances_possible_by_enquiry function using a

new enquiry and have all the matching instances loaded efficiently.

The definition of all the API calls for the new enquiry system are in the enq.h
header file and the Integration Toolkit Function Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

If you have legacy code, you can continue to use the old enquiry system. However,
only the newer enquiry system is described here. To make the code more readable,
the return values of the API calls are ignored in the examples. In ITK, you should
always check return values before proceeding to the next call.
How do I use it?
You do not have to be a SQL expert to use the enquiry system, but it helps if you
know a little, especially if you are trying to debug errors. This section describes the
basic ideas of the query system. Later, there is very detailed information which
describes more complex concepts.
Basic concepts
There are a number of basic building blocks for an enquiry. These are described
below and then the examples explain what you actually do with these and what
API calls to use.
Each enquiry has a unique name used to identify it. You specify the name when you
create the enquiry and must specify this name for anything you do with this enquiry.
Once you create an enquiry, it exists in memory until you delete it. Therefore, you
can access it using the unique name even if the tag for it has gone out of scope. It
also means you must clean it up explicitly once youve finished with it. An enquiry is
made up of a number of smaller parts:

SELECT attributes
The values you want to get back from the enquiry.

ORDER BY clauses
If you want your results to come back in a particular order, you can use an
ORDER BY. Note that this adds a SELECT attribute for the thing you are
ordering by.

4-50

Server Customization Programmers Guide

PLM00074 J

ITK customization

Attribute expressions
These allow you to control what data you want returned. These expressions
form the where part of the generated SQL statement. There are two main
types of attributes:
o

Fixed attributes
These are the same every time you run the enquiry. They can be simple
values (for example, name = Bill) or used to create joins between tables
(described below).

Bind variables
These allow different values to be passed to the database each time the
enquiry is run. These typically would be used either to find related objects
or for values that you do not know at compile time (for example, the value
of tags).

When you add attribute expressions, you normally give both the name of the
attribute and the class it is from.

Where clause
This combines a number of attribute expressions using different set expressions.
The most common one is AND.

These parts are the ones that you come across most often. There are a few more than
can be used; they are listed later in this document.
For example, compare the different building blocks with a very simple SQL
statement:
SELECT attr1 from table1 where attr3=test ORDER BY attr1

attr1 is a SELECT attribute

where attr3=test is a where clause and

attr3 and test are attribute expressions

ORDER BY attr1 is an ORDER BY clause

Basic steps to creating queries

If you create a POM enquiry, you must follow a number of steps and answer a
number of questions:
1. Create your query. Each query must have a unique name; it should be something
that you can recognize later and describes what it does.
2. Add the data you want returned to your enquiry.
3. Add any attributes you need for where clauses, joins, or other items.
4. Create expressions with the attributes from the previous step to make a where
clause.
5. Optionally, add an ORDER BY clause.

PLM00074 J

Server Customization Programmers Guide

4-51

Chapter 4

ITK customization

6. Execute the enquiry and extract the results.

7. Clean up.
Below are a number of examples that illustrate these steps for different cases.
Basic single table enquiry
This is a very simple case. This example finds all the workspace objects whose type
is equal to a string that is passed in. The following code shows a single bind variable
to compare strings:
/* Create enquiry and give it a name */
POM_enquiry_create (find_wso_by_type);
/* Add select attributes. We want the uids of the workspace
objects so we can load them: */
char * select_attrs[1] = {puid};
POM_enquiry_add_select_attrs (find_wso_by_type,
workspaceobject, 1, &select_attrs);
/* Add any attribute expressions. We need two of them one
for the value we are given and another for the attribute we are
testing against: */
POM_enquiry_set_string_value (find_wso_by_type, "test",
1,&name, POM_enquiry_bind_value );
POM_enquiry_set_attr_expr (find_wso_by_type, "expr1",
workspaceobject, "attr3",
POM_enquiry_equal, "test" );
/* Set the where condition so we only get back matching rows: */
POM_enquiry_set_where_expr (find_wso_by_type, "expr1");
/* Now execute the query: */
POM_enquiry_execute (find_wso_by_type, &n_rows,
&values);
Note

&n_cols,

In the example, expr1 is any string.

The program can then iterate through the results and copy the results. Once that is
done, the results array should be freed up using the MEM_free function.
Classes and attributes in POM queries
POM queries are largely built in terms of class and attribute names. Where a
class name is required, you can use the name of any POM class or any persistent
Teamcenter type. (POM enquiry does not support queries on run-time Teamcenter
types.) On execution, the query returns results from the instances of the class or
type you use. You do not need to know that names of the underlying database tables
that POM uses to store class or type instances.
An attribute is always associated with a class. Where an attribute name is required,
you can use the name of any of the classs attributes or any of its persistent
compound properties. (There are some cases where compound properties are not
supported.) You do not need to know the names of the underlying database columns
that POM uses to store the attributes.
For example, if you want to get the object_desc attribute of an item, you would refer
to it using the Item class and object_desc attribute. It does not matter that the
object_desc attribute is actually on the workspaceobject parent class or what the

4-52

Server Customization Programmers Guide

PLM00074 J

ITK customization

name of the column the data is stored in. The one exception is the puid attribute.
This is, in effect, the tag of the object and its unique identifier. If you want to load an
object or follow a reference from one object to another, you must use this attribute.
Compound properties and POM enquiry
POM enquiry supports queries on both attributes and on certain compound
properties. Whether a compound property is supported depends on how it is defined.
POM enquiry only supports compound properties:

Whose values are stored in the database (not those calculated at run time).

That are defined in terms of traversing POM references or Teamcenter relations

(not those defined in terms of traversing from an item to its item revision).

That are defined in terms of traversing to objects whose type is specified (rather
than in terms of traversing untyped references).

If the compound property value comes from a form, where the class used to store
the value is the one specified in the current property definition (rather than some
other class specified in a previous version of the definition).

Housekeeping
Once a POM enquiry has been created, it is available until it is deleted with the
POM_enquiry_delete function. Therefore, you can either:

Create the enquiry every time you use it and then delete it immediately
afterwards, or

Create it once and reuse it during the session.

Reusing an enquiry is more efficient. However, be careful in case your code is called
just before a POM_roll_to_markpoint function call or something else that undoes
any allocations in the POM. To protect yourself against this, use a static variable
and the POM_cache_for_session function. For example:
static tag_t my_tag = null_tag;
if (my_tag == null_tag)
{
/* Create enquiry objects, set up bind values, etc */

POM_cache_for_session( &my_tag );
my_tag = 1;
}
else
{
/* just set up bind values */

}
/* now execute the enquiry and use the results */

The POM_cache_for_session function adds to the variable passed to it the data

that is rolled back during an UNDO operation or the POM_roll_to_markpoint
function. If one of these occurs, then your variable is set back to its previous value
(in this case null_tag) and you know you have to create the enquiry again.

PLM00074 J

Server Customization Programmers Guide

4-53

Chapter 4

ITK customization

How to do a simple join

A join is when you link one table or object to another. For this example, use entries
in the Process Stage List array and use them to join to EPM tasks. The following
figure shows how they relate to each other.

Simple join
Each entry in the process_stage_list array points to an EPMTask using its puid
field. The example in the following code is more complicated. The information
you want is the object_name attribute on all the EPMTasks referenced by the
workspace object:
/* Create enquiry and give it a name */
POM_enquiry_create (find_referenced_task);
/* Add select attributes. We want the object_name of the Task: */
char * select_attrs[1] = {object_name};
POM_enquiry_add_select_attrs (find_referenced_task,
EPMTask, 1, &select_attrs);
/* Were starting from the workspace object, so we must add a
couple of attribute expressions for that:*/
/* This is going to be the tag we have for the WSO. */
POM_enquiry_set_tag_value (find_referenced_task , "wso_tag" , 1,
&object, POM_enquiry_bind_value )
POM_enquiry_set_attr_expr (find_referenced_task , "this_wso",\
"workspaceobject" , "puid" , POM_enquiry_equal , "wso_tag" )
/* And now join the workspace object to the EPMTasks via the
process_stage_list attribute on the workspace object */
POM_enquiry_set_join_expr (find_referenced_task , "task_join" ,
"workspaceobject" , "process_stage_list" ,
POM_enquiry_equal , "EPMTask" , "puid" )
/* All thats left now is to execute the query: */
POM_enquiry_execute (find_wso_by_type, &n_rows,
&n_cols, &values);

More advanced use

To fully understand and be able to create queries, you must understand the following
important terms and concepts:
Class alias
This is the equivalent of a table alias in the SQL-92 standard. The class alias
is very useful if you want to define a query that has a self-join. The classic
example of this is employees and managers (Find the list of managers and their
employees).

4-54

Server Customization Programmers Guide

PLM00074 J

ITK customization

Pseudo class
The pseudo class represents a compound attribute of a given Teamcenter class.
The attribute must be either a:

Large array (LA) or

Variable length array (VLA)

This is useful if you want to query the LA or VLA based on a condition on one
of the array attribute.
Set expression
This is the way of combining the result of two or more queries into one using
(UNION,...). The queries must be union-compatible (in other words, they must
have the same number of attributes selected and they must respectively be
of the same domain).
Expression
There are two types of expressions that can be built in an SQL statement. These
are:

Logical expressions
Any expression that results to a logical value (true or false). For example, A
or B, ( A and B ) or C, A=B, A>=B, A IS NULL, A in [a,b,c].

Function expressions
Any expression that uses a function to manipulate an attribute. For example,
SUBSTR ( A,1,14), UPPER, A+B,LOWER(A), MAX(A), MIN(A), A+B,A/B.

Escape character
Teamcenter provides two special wildcard characters:
POM_wildcard_character_one and POM_wildcard_character_any. You
can set these values by calling the POM_set_env_info function. However, if the
string contains any of these wildcard characters as part of the data, you have no
way of telling Teamcenter how to treat these values. For this reason, there is a
token for the escape character called POM_escape_character.
You can set this character in the same way as for the
POM_wildcard_character_any or POM_wildcard_character_one
characters, by calling the POM_set_env_info function with its first argument
POM_escape_character token. If any of the wildcard characters is part of the
data, then you must escape it with the chosen escape character.
Note

If the escape character is found in the string and is not followed by

either the wildcard characters or itself, the POM removes it from
the string.

The PUID, PSEQ and PVAL keywords are reserved Teamcenter

words.
PUID can be used as an attribute of any POM class. PSEQ and
PVAL can only be used as attributes of a pseudo-class.

PLM00074 J

Server Customization Programmers Guide

4-55

ITK customization

Chapter 4

Query specification
The SQL-92 standard query specification consists of the following clauses:

SELECT select-list

FROM class-list

[ WHERE search-condition ]

[ ORDER BY attribute-list ]

[ GROUP BY attribute-list ]

[ HAVING search-condition ]

Clauses enclosed by brackets [ ] are optional.

Building expressions
The POM enquiry system APIs contain a list of functions that can be used to build
expressions.
Function

Description

POM_enquiry_set_attr_expr

This is the recommended way for creating

expressions on class.attr. It is used as follows:
Create a type value:
POM_enquiry_set_type_value (enqid, valid,
n_values, values, property); here property can
be either POM_enquiry_const_value or
POM_enquiry_bind_value.
Create the expression:
POM_enquiry_set_attr_expr (enqid, exprid,
class, attr, operator, valid)
Note

4-56

Server Customization Programmers Guide

valid cannot be NULL. If the right-hand

side of the expression is NULL such
as for the unary operators UPPER
and LOWER, you must create (char
*valid="").

PLM00074 J

ITK customization

Function

Description

POM_enquiry_set_type_expr This is a convenient function that avoids the

need to create a value. It is used as follows:
POM_enquiry_set_type_expr (enqid, exprid,
class, attr, operator, type, value)
type must be the type of the attribute in
question. type can be: int, double, char,
string, logical, tag_t, date_t. In the case
of tag_t and date_t, the function name
is POM_enquiry_set_tag_expr and
POM_enquiry_set_date_expr. However, this
function cannot be used to create expressions
on class.attr where the class has no associated
database table (such POM_system_class). Use
the POM_enquiry_set_attr_expr function
instead.
POM_enquiry_set_expr

This function is used to combine two expressions

into one. For example, - expr1 OR expr2,
expr1 AND expr2. - UPPER ( SUBSTR ( A,
1,14 )). - expr1 theta-op expr2 where theta-op
can be: =,>,>=,<,<=.... ( a+b)*c.
Note

If you have an expression like

the following: (class.attr1 +
class.attr2)/class.attr3 in the
select-clause, you need to add an
expression to the where-clause as
follows: ( (class.attr3 > 0) AND
(class.attr3 IS NOT NULL)).

Practical example
For example, if you want to find the name and type of all objects created since March
8, 2005, the SQL statement is:
SELECT object_name, object_type FROM WorkspaceObject WHERE creation_date >=
08-Mar-2005 00:00

The POM enquiry APIs required to create this query are shown in the following code:
void ***report;
int n_rows, n_cols, row, column;
const char *select_attr_list[] = { "object_name", "object_type"};
date_t aDate;
ITK_string_to_date("08-Mar-2005 00:00", &aDate);
/*create a query*/
POM_enquiry_create("aEnqId");
/*add the list to the select clause of the query*/
POM_enquiry_add_select_attrs("aEnqId", "WorkspaceObject", 2, select_attr_list);
/*create a date value object.*/
POM_enquiry_set_date_value("aEnqId", "aValId", 1, &aDate,
POM_enquiry_bind_value);
/* create an expression for pcreation_date = Date using the value "aValId" */
POM_enquiry_set_attr_expr("aEnqId", "aExpId", "WorkspaceObject",
"creation_date", POM_enquiry_greater_than_or_eq, "aValId");

PLM00074 J

Server Customization Programmers Guide

4-57

Chapter 4

ITK customization

/*set the where clause search condition.*/

POM_enquiry_set_where_expr( "aEnqId", "aExpId"));
/*execute the query*/
POM_enquiry_execute("aEnqId", &n_rows, &n_cols, &report);
for (row = 0; row < n_rows; row++)
{
for (column = 0; column < n_cols; column++)
printf("%s\t", report[row][column]);
printf("\n");
}

Data in the report variable can be read as report[i][j] where i is the row and j
is the column.
As can be seen from the previous example, the FROM clause was not defined. It is
automatically derived from the other clauses of the query.
SELECT clause
The SELECT list of an SQL statement consists of a list of attributes and expressions.
The operator of the expression must be a valid one supported by the RDBMS in use.
The following are supported: +, -, /, *, substr, upper, lower, contact, to_number,
to_date, cpid_of, uid_of, max, min, avg, count all, count distinct, and sum.
Refer to the Supported operators table for valid token names supported by the
enquiry system.
For example, if you want to find all the objects created by the users Ahmed, Hewat,
and James, the SQL statement would be:
SELECT pa.object_name,pr.user_name FROM pom_application_object pa, user ur,
person pr WHERE ur.person = pr.puid and pr.puid = pa.puid and
pr.user_name in (Ahmed,Hewat,James)

The POM enquiry APIs required to create this query are as follows:
As can be seen from the previous SQL statement, the object_name and user_name
attributes do not belong to the same class. Therefore you need to call the
POM_enquiry_add_select_attrs function twice, as shown in the following code:
/*create variables for POM_enquiry_execute*/
int rows,cols;
void *** report;
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
/*create two variables called select_attr_list1 and select_attr_list2 */
const char * select_attr_list1[] = { "object_name"};
const char * select_attr_list2[] = { "user_name" };
/*create a variable value_list */
const char * value_list[] = {"Ahmed","Hewat", "James"};
POM_enquiry_add_select_attrs ( "a_unique_query_id", "pom_application_object", 1,
select_attr_list1 );
POM_enquiry_add_select_attrs ( "a_unique_query_id", "person", 1, select_attr_list2
);
/*Create the join expr ur.rpersonu = pr.puid*/
POM_enquiry_set_join_expr ("a_unique_query_id","auniqueExprId_1","user","person",
POM_enquiry_equal,"person","puid"
);
/*Create the join expr pr.puid = pa.puid*/
POM_enquiry_set_join_expr ("a_unique_query_id","auniqueExprId_2","person","puid",
POM_enquiry_equal,"pom_application_object","puid"
);
/*Create a tag value.*/

4-58

Server Customization Programmers Guide

PLM00074 J

ITK customization

POM_enquiry_set_string_value ( "a_unique_query_id", "aunique_value_id", 3, value_list,

POM_enquiry_bind_value );
/*Create the expression user_name in (Ahmed,Hewat,James).*/
POM_enquiry_create_attr_expr ( "a_unique_query_id","auniqueExprId_3", "person",
"user_name",
POM_enquiry_in, "aunique_value_id" );
/*Combine the expr_1 and expr_2 using AND.*/
POM_enquiry_set_expr ( "a_unique_query_id","auniqueExprId_4", "auniqueExprId_1",
POM_enquiry_and, "auniqueExprId_2" );
/*Combine the expr_3 and expr_4 using AND.*/
POM_enquiry_set_expr ( "a_unique_query_id","auniqueExprId_5", "auniqueExprId_3",
POM_enquiry_and, "auniqueExprId_4" );
/*Set the where clause of the query*/
POM_enquiry_set_where_expr ( "a_unique_query_id","auniqueExprId_5" );
/*Execute the query.*/
POM_enquiry_execute ( "a_unique_query_id",&row,&cols,&report);
/*Delete the query*/
POM_enquiry_delete ( "a_unique_query_id" );

Notice that the POM_enquiry_bind_value token specifies that the query can be
rerun with different values without the need to re-evaluate the query. Also by using
bind variables, you are telling the database server to cache the plan of the execution
of the SQL statement which saves time.
FROM clause
The FROM clause of the query is automatically generated.
WHERE clause
The WHERE clause of a query restricts the result to only those rows that verify
the condition supplied.
For example, if you want to find the name and type of all objects created between
date1 and date2, the SQL statement is:
SELECT object_name,object_type FROM pom_application_object WHERE creation_date
BETWEEN date1 and date2

The POM enquiry APIs required to create this query are shown in the following code:
/*create variables for POM_enquiry_execute*/
int rows,cols;
void *** report;
/*create a query*/
POM_enquiry_create ("a unique query id")
/*create a variable called select-attr_list*/
const char * select_attr_list[] = { "object_name","object_type"};
/*add the list to the select clause of the query*/
POM_enquiry_add_select_attrs ("a unique query id" , "pom_application_object", 2 ,
select_attr_list );
/*create two date_t variables.*/
const date_t aDate1;
const date_t aDate2;
const date_t date_list[2];
/*initialize adate1. */
aDate1.day = day1; aDate1.month = month1; aDate1.year = year1; aDate1.hours = 0;
aDate1.minutes = 0;
aDate1.seconds = 0;
/*initialize adate2. */
aDate2.day = day2; aDate2.month = month2; aDate2.year = year2; aDate2.hours = 0;
aDate2.minutes = 0;
aDate2.seconds = 0;
date_list[0]=aDate1;

PLM00074 J

Server Customization Programmers Guide

4-59

Chapter 4

ITK customization

date_list[1]=aDate2;
/*create a date value object.*/
POM_enquiry_set_date_value ("a unique query id" , "auniquevalueId", 2 , date_list
, POM_enquiry_bind_value );
/*create an expression for pcreation_date between aDate1 and aDate2 using the value
"auniquevalueId"*/
POM_enquiry_set_attr_expr ("a unique query id","auniqueExprId","pom_application_object",
"creation_date",POM_enquiry_between,"auniquevalueId");
/*set the where clause search condition.*/
POM_enquiry_set_where_expr ( "a unique query id","auniqueExprId");
/*execute the query*/
POM_enquiry_execute ( "a unique query id",&row,&cols,&report);
/*Delete the query*/
POM_enquiry_delete ( "a_unique_query_id" );

ORDER BY clause
The ORDER BY list of an SQL statement consists of a list of attributes and
expressions. The operator of the expression must be a valid one supported by the
RDBMS in use.
Refer to the Supported operators table for valid token names supported by the
enquiry system.
For example, if you want to find all the objects created by the users Ahmed, Hewat
and James ordered by the user_name attribute, the SQL statement is:
SELECT pa.pobject_name,pr.user_name FROM ppom_application_object pa, puser ur,
pperson pr WHERE ur.rpersonu = pr.puid and pr.puid = pa.puid and pr.puser_name
in (Ahmed,Hewat,James) ORDER BY user_name

As can be seen from the previous SQL statement, the object_name and
user_name attributes do not belong to the same class, therefore you need to call the
POM_enquiry_add_select_attrs function twice. The POM enquiry APIs required
to create this query are shown in the following code:
/*create variables for POM_enquiry_execute*/
int rows,cols;
void *** report;
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
/*create two variables called select_attr_list1 and select_attr_list2 */
const char * select_attr_list1[] = { "object_name"};
const char * select_attr_list2[] = { "user_name" };
/*create a variable value_list */
const char * value_list[] = {"Ahmed","Hewat", "James"};
POM_enquiry_add_select_attrs ( "a_unique_query_id", "pom_application_object", 1,
select_attr_list1 );
POM_enquiry_add_select_attrs ( "a_unique_query_id", "person", 1, select_attr_list2
);
/*Create the join expr ur.rpersonu = pr.puid*/
POM_enquiry_set_join_expr ("a_unique_query_id","auniqueExprId_1","user","person",
POM_enquiry_equal,"person","puid"
);
/*Create the join expr pr.puid = pa.puid*/
POM_enquiry_set_join_expr ("a_unique_query_id","auniqueExprId_2","person","puid",
POM_enquiry_equal,"pom_application_object","puid"
);
/*Create a tag value.*/
POM_enquiry_set_string_value ( "a_unique_query_id", "aunique_value_id", 3, value_list,
POM_enquiry_bind_value );
/*Create the expression user_name in (Ahmed,Hewat,James).*/
POM_enquiry_create_attr_expr ( "a_unique_query_id","auniqueExprId_3", "person",
"user_name",
POM_enquiry_in, "aunique_value_id" );

4-60

Server Customization Programmers Guide

PLM00074 J

ITK customization

/*Combine the expr_1 and expr_2 using AND.*/

POM_enquiry_set_expr ( "a_unique_query_id","auniqueExprId_4", "auniqueExprId_1",
POM_enquiry_and, "auniqueExprId_2" );
/*Combine the expr_3 and expr_4 using AND.*/
POM_enquiry_set_expr ( "a_unique_query_id","auniqueExprId_5", "auniqueExprId_3",
POM_enquiry_and, "auniqueExprId_4" );
/*Set the where clause of the query*/
POM_enquiry_set_where_expr ( "a_unique_query_id","auniqueExprId_5" );
/*set the order by clause.*/
POM_enquiry_add_order_attr ( "a_unique_query_id","Person","user_name",
POM_enquiry_asc_order
);
/*Execute the query.*/
POM_enquiry_execute ( "a_unique_query_id",&row,&cols,&report);
/*Delete the query*/
POM_enquiry_delete ( "a_unique_query_id" );

GROUP BY clause
This the same as the ORDER BY clause except for the sorting
order. Just replace the POM_enquiry_add_order_attr
function with the POM_enquiry_add_group_attr function
and the POM_enquiry_add_order_expr function with the
POM_enquiry_add_group_expr function.
HAVING clause
This is the same as the WHERE clause. Replace the
POM_enquiry_set_where_expr function with the
POM_enquiry_set_having_expr function.
Subqueries
For example, if you want to find the list of folders whose contents attribute contains
a UGMASTER type dataset, the SQL statement is:
SELECT f1.puid FROM folder f1 WHERE f1.contents in ( SELECT ds.puid FROM
dataset ds WHERE ds.object_type = UGMASTER );

The POM enquiry APIs required to create this query are shown in the following code:
/*create variables for POM_enquiry_execute*/
int rows,cols;
void *** report;
/*create a variable select_attr_list */
const char * select_attr_list[] = {"puid"};
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
As can be seen from the above pseudo-SQL statement contains a subquery.
Hence the need for creating one.
/*Create a subquery.*/
POM_enquiry_set_sub_enquiry ( "a_unique_query_id", "subquery_unique_id" );
/* select the puid from Folder class.*/
POM_enquiry_add_select_attrs ( "a_unique_query_id", "Folder", 1, select_attr_list
);
/* select the puid from Dataset class.*/
POM_enquiry_add_select_attrs ( "subquery_unique_id", "Dataset", 1, select_attr_list
);
/*Create the expr ds.type = UGMASTER.*/
POM_enquiry_set_string_expr ("subquery_unique_id","auniqueExprId_1","Dataset",
"object_type",POM_enquiry_equal,"UGMASTER"
);

PLM00074 J

Server Customization Programmers Guide

4-61

Chapter 4

ITK customization

/*Set the subquery where clause.*/

POM_enquiry_set_where_expr ( "subquery_unique_id","auniqueExprId_1" );
/*Create the expr f1.contents in subquery.*/
POM_enquiry_set_attr_expr ("a_unique_query_id","auniqueExprId_2","Folder","contents",
POM_enquiry_in,"subquery_unique_id"
);
/*Set the outer query where clause.*/
POM_enquiry_set_where_expr ( "a_unique_query_id","auniqueExprId_7" );
/*Execute the outer query.*/
POM_enquiry_execute ( "a_unique_query_id",&row,&cols,&report);
/*Delete the query*/
POM_enquiry_delete ( "a_unique_query_id" );
Note

The POM_enquiry_in function can be replaced by

the POM_enquiry_not_in, POM_enquiry_exists, or
POM_enquiry_not_exists function.

For IN, NOT IN, EXISTS and NOT EXISTS operators, see your RDBMS reference
manual.
Use of class_alias
For example, if you want to find the list of folders whose contents attribute contains
a folder of type override and its contents has an item revision X, the pseudo-SQL is:
select f1.puid from folder f1,folder f2, item_revision itr where f1.contents
= f2.puid and f2.type = override and f2.contents = itr.puid and
itr.object_name = X;

The folder class appears twice in the from clause and therefore needs a class alias.
The POM enquiry APIs required to create this query are shown in the following code:
/*create variables for POM_enquiry_execute*/
int rows,cols;
void *** report;
/*create a variable select_attr_list */
const char * select_attr_list[] = {"puid"};
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
/*Create a class alias for the Folder class.*/
POM_enquiry_create_class_alias ( "a_unique_query_id", "Folder",1,"Folder_alias");
/* select the puid from Folder class.*/
POM_enquiry_add_select_attrs ( "a_unique_query_id", "Folder", 1, select_attr_list
);
/*Create the join expr f1.contents = f2.puid*/
POM_enquiry_set_join_expr ("a_unique_query_id","auniqueExprId_1","Folder","contents",
POM_enquiry_equal,"Folder_alias","puid"
);
/*Create the expr f2.type = override.*/
POM_enquiry_set_string_expr ("a_unique_query_id","auniqueExprId_2","Folder_alias","type",
POM_enquiry_equal,"override"
);
/*Create the join expr f2.contents = itr.puid*/
POM_enquiry_set_join_expr ("a_unique_query_id","auniqueExprId_3","Folder_alias",
"contents",POM_enquiry_equal,"Item_revision","puid"
);
/*Create the expr itr.object_name = X.*/
POM_enquiry_set_string_expr ("a_unique_query_id","auniqueExprId_4","Folder_alias",
"object_name",POM_enquiry_equal,"X"
);
/*Combine the expr_1 and expr_2 using AND.*/
POM_enquiry_set_expr ( "a_unique_query_id","auniqueExprId_5", "auniqueExprId_1",
POM_enquiry_and, "auniqueExprId_2" );

4-62

Server Customization Programmers Guide

PLM00074 J

ITK customization

/*Combine the expr_3 and expr_4 using AND.*/

POM_enquiry_set_expr ( "a_unique_query_id","auniqueExprId_6", "auniqueExprId_3",
POM_enquiry_and, "auniqueExprId_4" );
/*Combine the expr_5 and expr_6 using AND.*/
POM_enquiry_set_expr ( "a_unique_query_id","auniqueExprId_7", "auniqueExprId_5",
POM_enquiry_and, "auniqueExprId_6" );
/*Set the where clause of the query*/
POM_enquiry_set_where_expr ( "a_unique_query_id","auniqueExprId_7" );
/*Execute the query.*/
POM_enquiry_execute ( "a_unique_query_id",&row,&cols,&report);
/*Delete the query*/
POM_enquiry_delete ( "a_unique_query_id" );

Use of pseudo_class
For example, if you want to find all versions of the dataset X, the pseudo-SQL is:
select ds.puid from dataset ds, revisionAnchor rva where ds.rev_chain_anchor
= rva.puid and rva.revisions.PSEQ = 0 and ds.object_name = X

The PSEQ attribute in the where clause is not a POM_attribute and the revisions
is not a POM_class. Since the only classes you are allowed to query on are
POM_classes, you have to convert the revisions attribute of the revisionAnchor
into a POM_class. To do this, create a pseudo-class on the attribute revisions of
the revisionAnchor.
Note

You can only create pseudo-classes for VLA or LA attributes.

The POM enquiry APIs required to create this query are shown in the following code:
/* Create variables for POM_enquiry_execute*/
int rows,cols;
void *** report;
/* Create a variable select_attr_list */
const char * select_attr_list[] = {"puid"};
/* Create a variable int_val=0*/
const int int_val = 0;
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
/* Create a pseudo-class for the revisionAnchor.revisions attribute.*/
POM_enquiry_set_pseudo_calias ( "a_unique_query_id", "RevisionAnchor","revisions",
"class_revisions");
/* Select the puid from Dataset class.*/
POM_enquiry_add_select_attrs ( "a_unique_query_id", "Dataset", 1, select_attr_list);
/* Create the expr rva.revisons.pseq = 0.*/
/* First create an int value.*/
POM_enquiry_set_int_value ( "a_unique_query_id","auniqueValueId", 1, &int_val,
POM_enquiry_bind_value
);
POM_enquiry_set_attr_expr ("a_unique_query_id","auniqueExprId_1","class_revisions","pseq",
POM_enquiry_equal,"auniqueValueId"
);
/* NOTICE: the pseq attribute is reserved keyword in TC/POM, it can be used as an
attribute of the pseudo-class. The same
apply to pval and puid. */
/* Create the expr ds.object_name = X.*/
POM_enquiry_set_string_expr ("a_unique_query_id","auniqueExprId_2","Dataset",
"object_name",POM_enquiry_equal,"X"
);
/* Create the join expr ds.rev_chain_anchor = rva.puid */
POM_enquiry_set_join_expr ("a_unique_query_id","auniqueExprId_3","Dataset",
"rev_chain_anchor",POM_enquiry_equal,"revisionAnchor","puid");
/* Combine the expr_1 and expr_2 using AND.*/
POM_enquiry_set_expr ( "a_unique_query_id","auniqueExprId_4", "auniqueExprId_1",

PLM00074 J

Server Customization Programmers Guide

4-63

Chapter 4

ITK customization

POM_enquiry_and, "auniqueExprId_2" );
/* Combine the expr_3 and expr_4 using AND.*/
POM_enquiry_set_expr ( "a_unique_query_id","auniqueExprId_5", "auniqueExprId_3",
POM_enquiry_and, "auniqueExprId_4" );
/* Set the where clause of the query*/
POM_enquiry_set_where_expr ( "a_unique_query_id","auniqueExprId_5" );
/* Execute the query.*/
POM_enquiry_execute ( "a_unique_query_id",&row,&cols,&report);
/* Delete the query*/
POM_enquiry_delete ( "a_unique_query_id" );

Use of Set-Expression
Use set operators to find objects in different sets.
INTERSECTION
For example, if you want to find all the objects that are common to two folders,
the pseudo SQL is as follows:
select f1.contents from folder f1 where f1.object_name=Compare INTERSECTION
select f2.contents from folder f2 where f2.object_name=Reference

The pseudo SQL consists of two queries that are combined by the INTERSECTION
set operator. In this case, one of the queries must be the outer query and the other
one must be scoped to it. Therefore, the non-outer query must be created as a
subquery of the outer one.
The POM enquiry APIs required to create this query are shown in the following code:
/* Create variables for POM_enquiry_execute*/
int rows,cols;
void *** report;
/* Create a variable select_attr_list */
const char * select_attr_list[] = {"contents"};
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
/* Select the contents from Folder class.*/
POM_enquiry_add_select_attrs ( "a_unique_query_id", "Folder", 1, select_attr_list );
/* Now limit it to just the folder we want to see */
/* Folder names are not always unique so for a real example you should */
/* use the tag of the folder */
POM_enquiry_set_string_expr ("a_unique_query_id","auniqueExprId_1","Folder", "object_name",
POM_enquiry_equal, "Compare" );
/* Set the outer query where clause.*/
POM_enquiry_set_where_expr ( "a_unique_query_id","auniqueExprId_1" );
/* POM implements set queries as subqueries and so we need to create one */
POM_enquiry_set_sub_enquiry ( "a_unique_query_id", "subquery_unique_id" );
/* Create a class alias for the Folder class. The folder class is appearing twice - once */
/* in the outer query and the other time in the subquery. */
POM_enquiry_create_class_alias ( "subquery_unique_id", "Folder",1,"Folder_alias");
/* Select the contents from other folder.*/
POM_enquiry_add_select_attrs ( "subquery_unique_id", "Folder_alias", 1, select_attr_list);
POM_enquiry_set_string_expr ("a_unique_query_id","auniqueExprId_2","Folder_alias",
"object_name", POM_enquiry_equal, "Reference" );
/* Set the subquery where clause.*/
POM_enquiry_set_where_expr ( "subquery_unique_id","auniqueExprId_2" );
/* Add the set expression */
POM_enquiry_set_setexpr ("a_unique_query_id, POM_enquiry_intersection,
"subquery_unique_id");
/* Execute the outer query.*/
POM_enquiry_execute ( "a_unique_query_id",&row, &cols, &report);
/* Delete the query*/
POM_enquiry_delete ( "a_unique_query_id" );

4-64

Server Customization Programmers Guide

PLM00074 J

ITK customization

DIFFERENCE
For example, if you want to find all the objects that are in a reference folder that do
not exist in a named folder, the pseudo SQL is:
select f1.contents from folder f1 where f1.object_name=Reference DIFFERENCE
select f2.contents from folder f2 where f2.object_name=Compare

The pseudo SQL consists of two queries that are combined by the DIFFERENCE
set operator. In this case, one of the queries must be the outer query and the other
one must be scoped to it. Therefore, the non-outer query must be created as a
subquery of the outer one.
The POM enquiry APIs required to create this query are shown in the following code:
/*create variables for POM_enquiry_execute*/
int rows,cols;
void *** report;
/*create a variable select_attr_list */
const char * select_attr_list[] = {"contents"};
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
/* select the contents from Folder class.*/
POM_enquiry_add_select_attrs ( "a_unique_query_id", "Folder", 1, select_attr_list );
/* Now limit it to just the folder we want to see */
/* Folder names are not always unique so for a real example you should */
/* use the tag of the folder */
POM_enquiry_set_string_expr ("a_unique_query_id","auniqueExprId_1","Folder", "object_name",
POM_enquiry_equal, "Reference" );
/*Set the outer query where clause.*/
POM_enquiry_set_where_expr ( "a_unique_query_id","auniqueExprId_1" );
/* POM implements set queries as subqueries and so we need to create one */
POM_enquiry_set_sub_enquiry ( "a_unique_query_id", "subquery_unique_id" );
/* Create a class alias for the Folder class. The folder class is appearing twice - once */
/* in the outer query and the other time in the subquery. */
POM_enquiry_create_class_alias ( "subquery_unique_id", "Folder",1,"Folder_alias");
/* select the contents from other folder.*/
POM_enquiry_add_select_attrs ( "subquery_unique_id", "Folder_alias", 1, select_attr_list);
POM_enquiry_set_string_expr ("a_unique_query_id","auniqueExprId_2","Folder_alias",
"object_name", POM_enquiry_equal, "Compare" );
/*Set the subquery where clause.*/
POM_enquiry_set_where_expr ( "subquery_unique_id","auniqueExprId_2" );
/* Add the set expression */
POM_enquiry_set_setexpr ("a_unique_query_id, POM_enquiry_difference, "subquery_unique_id");
/*Execute the outer query.*/
POM_enquiry_execute ( "a_unique_query_id", &row, &cols, &report);
/*Delete the query*/
POM_enquiry_delete ( "a_unique_query_id" );

UNION
For example, you have two forms: FORM1 and FORM2. FORM1 is an engineering
type form that has two attributes: weight and material. FORM2 is a production
type form and has two attributes: cost and effectivity_date.
If you want to find all engineering type objects that weigh more than wt1 and all
production type objects that cost less than cost1, the pseudo SQL is:
Select f1.puid From FORM1 Where f1.type = engineering And f1.weight > wt1
UNION Select f2.puid From FORM2 Where f2.type = Production And
f2.cost < cost1

The POM enquiry APIs required to create this query are shown in the following code:
/* create variables for POM_enquiry_execute*/
int rows,cols;

PLM00074 J

Server Customization Programmers Guide

4-65

Chapter 4

ITK customization

void *** report;

/* Create a variable select_attr_list */
const char * select_attr_list[] = {"puid"};
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
/* Select the puid from FORM1 class.*/
POM_enquiry_add_select_attrs ( "a_unique_query_id", "form1", 1, select_attr_list);
/* Create the expr f1.type = engineering*/
POM_enquiry_set_string_expr ( "a_unique_query_id","auniqueExprId_1","form1","object_type",
POM_enquiry_equal,"engineering");
/* Create the expr f1.weight > wt1*/
POM_enquiry_set_double_expr ( "a_unique_query_id","auniqueExprId_2","form1","weight",
POM_enquiry_greater_than,wt1);
/* Combine expr1 and expr2 using AND operator.*/
POM_enquiry_set_expr ( "a_unique_query_id", "auniqueExprId_3", "auniqueExprId_1",
POM_enquiry_and,"auniqueExprId_2" );
/* Set the where clause of the outer query*/
POM_enquiry_set_where_expr ( "a_unique_query_id","auniqueExprId_3" );
/* Create a subquery*/
POM_enquiry_set_sub_enquiry ("a_unique_query_id", "subquery_unique_id" )
/* Select the puid from FORM2 class.*/
POM_enquiry_add_select_attrs ( "subquery_unique_id", "form2", 1, select_attr_list
);
/* Create the expr f2.cost <cost1*/
POM_enquiry_set_double_expr ( "subquery_unique_id","auniqueExprId_5","form2",
"cost",POM_enquiry_less_than,cost1 );
/* Combine expr4 and expr5 using AND operator.*/
POM_enquiry_set_expr ( "subquery_unique_id", "auniqueExprId_6", "auniqueExprId_4",
POM_enquiry_and, "auniqueExprId_5" );
/* Set the where clause of the subquery*/
POM_enquiry_set_where_expr ( "subquery_unique_id","auniqueExprId_6" );
/* Now we need to set the set-expression of the outer query. */
POM_enquiry_set_setexpr ( "a_unique_query_id" ,"setexpr",POM_enquiry_union ,
"subquery_unique_id" );
/* Execute the query.*/
POM_enquiry_execute ( "a_unique_query_id",&row,&cols,&report);
/* Delete the query*/
POM_enquiry_delete ( "a_unique_query_id" );

Special operators
You can use special operators to create certain expressions.
POM_enquiry_substr
If you want to create the expression SUBSTR (item.desc,1,5)=blob, you can use
the enquiry APIs as shown in the following code:
/*Create a variable int_list*/
const int int_list[]={1,5};
/*Create a string variable*/
const char *str_list[]={"blob"};
/* First we nned to create an int value:*/
POM_enquiry_set_int_value ( "a_unique_query_id","auniqueValueId_1",1,int_list,
POM_enquiry_const_value);
/* Create the expression SUBSTR ( item.desc, 1,5) using the int value.*/
POM_enquiry_set_attr_expr ( "a_unique_query_id", "auniqueExprId_1","item","desc",
POM_enquiry_substr,"auniqueValueId_1")
/* Create a string value = blob.*/
POM_enquiry_set_int_value ( "a_unique_query_id","auniqueValueId_2",1,str_list,
POM_enquiry_bind_value);
/* Create the expression SUBSTR ( item.desc, 1,5) = blob.*/
POM_enquiry_set_expr ( "a_unique_query_id","auniqueExprId_2", "auniqueExprId_1",
POM_enquiry_equal, "auniqueValueId_2");

4-66

Server Customization Programmers Guide

PLM00074 J

ITK customization

POM_enquiry_cpid_of
For example, if you want to find all the dataset objects of a folder, the pseudo SQL is:
Select contents From Folder Where cpid_of ( contents ) = dataset cpid

The way to implement this query in the old query system is to use a join between
dataset and folder contents. To avoid the performance penalty of using the join, you
can use the POM_enquiry_cpid_of special operator.
Note

POM_enquiry_cpid_of can only be used with typed or untyped_reference

type attributes.

/*Find the cpid of dataset class by using:*/

POM_class_id_of_class ("dataset",&classid );
POM_class_to_cpid ( classid, &cpid );
/*create variables for POM_enquiry_execute*/
int rows,cols;
void *** report;
/*create a variable select_attr_list */
const char * select_attr_list[] = {"contents"};
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
/* select the puid from folder class.*/
POM_enquiry_add_select_attrs ( "a_unique_query_id", "folder", 1, select_attr_list);
/*create an int value*/
POM_enquiry_set_int_value ( "a_unique_query_id", "auniqueValueId_1", 1, &cpid,
POM_enquiry_bind_value);
/* Create the expression cpid_of( contents ).*/
POM_enquiry_set_attr_expr ( "a_unique_query_id", "auniqueExprId_1", "folder", "contents",
POM_enquiry_cpid_of, "" );
/*Set the expression cpid_of ( contents ) = dataset cpid.*/
POM_enquiry_set_expr ( "a_unique_query_id", "auniqueExprId_2","auniqueExprId_1",
POM_enquiry_equal,"auniqueValueId");
/*Set the where clause of the query*/
POM_enquiry_set_where_expr ( "a_unique_query_id","auniqueExprId_2" );
/*Execute the query.*/
POM_enquiry_execute ( "a_unique_query_id",&row,&cols,&report);
/*Delete the query*/
POM_enquiry_delete ( "a_unique_query_id" );

POM_enquiry_upper and POM_enquiry_lower

If you want to create the expression UPPER(item.desc )= UPPER(blob), you can
use the enquiry APIs as shown in the following code:
/*Create a string variable*/
const char *str_list[]={blob};
/* Create the expression UPPER( item.desc).*/
POM_enquiry_set_attr_expr ( "a_unique_query_id", "auniqueExprId_1","item","desc",
POM_enquiry_upper,"")
/* Create a string value = blob.*/
POM_enquiry_set_int_value ( "a_unique_query_id","auniqueValueId_2",1,str_list,
POM_enquiry_bind_value);
/* Create the expression UPPER( item.desc) = UPPER(blob).*/
POM_enquiry_set_expr ( "a_unique_query_id","auniqueExprId_2", "auniqueExprId_1",
POM_enquiry_equal, "auniqueValueId_2");
Note

PLM00074 J

When you apply the upper or lower operator to the left hand side of an
expression, the operator is applied automatically to the right hand side of
the expression.

Server Customization Programmers Guide

4-67

ITK customization

Chapter 4

POM_enquiry_countdist
If you want to create the expression COUNT(DISTINCT item.puid ), you can use
the enquiry APIs as shown in the following code:
/* Create the expression COUNT(DISTINCT item.desc).*/
POM_enquiry_set_attr_expr ( "a_unique_query_id", "auniqueExprId_1","item","puid",
POM_enquiry_countdist,"")
Note

You cannot use count ( * ). Instead use COUNT ( ALL class.puid

) by using the POM_enquiry_countall. To return only the number
of distinct rows, use COUNT (DISTINCT class.puid ), by using the
POM_enquiry_countdist.

The same apply to MAX, MIN, AVG, and SUM except that these apply to different
attributes of the class, not the puid.
POM_enquiry_in and POM_enquiry_not_in
These operators can be used either with a subquery or a list of values. Oracle
imposes some restrictions on the number of values allowed in the in-list when using
bind variables. These are:

The number of bind values is limited to 254.

If you create a query with more than MAX_BIND_VALUE bind variables, the
new query system converts the bind values into constants and construct a query
that can be successfully executed. However, the SQL statement is not cached
and therefore risks flooding the System Global Area (SGA).

Supported operators
The following table shows the operators that are supported in the POM enquiry
module.

Operator

4-68

Where it
can be
used

POM_enquiry_or

Left
expr

Right
expr

POM_enquiry_and

expr

expr

WH

POM_enquiry_equal

attr/expr

expr/value

WH

POM_enquiry_not_equal

attr/expr

expr/value

WH

POM_enquiry_greater_than

attr/expr

expr/value

WH

POM_enquiry_greater_than_
or_eq

attr/expr

expr/value

WH

POM_enquiry_less_than

attr/expr

expr/value

WH

POM_enquiry_less_than_or_eq attr/expr

expr/value

WH

POM_enquiry_between

attr/expr

expr/value

WH

POM_enquiry_not_between

attr/expr

expr/value

WH

POM_enquiry_in

attr/expr

value/
subquery

WH

Server Customization Programmers Guide

WH

PLM00074 J

ITK customization

PLM00074 J

Where it
can be
used

Operator

Left

Right

POM_enquiry_not_in

attr/expr

value/
subquery

WH

POM_enquiry_exists

attr/expr

subquery

WH

POM_enquiry_not_exists

attr/expr

subquery

WH

POM_enquiry_like

attr/expr

value

WH

POM_enquiry_not_like
POM_enquiry_union

attr/expr
query

value
query

WH
-

POM_enquiry_difference

query

query

POM_enquiry_intersection

query

query

POM_enquiry_countdist

attr

null

SH

POM_enquiry_countall

attr

null

SH

POM_enquiry_max

attr

null

SH

POM_enquiry_min

attr

null

SH

POM_enquiry_avg

attr

null

SH

POM_enquiry_sum

attr

null

SH

POM_enquiry_plus

attr/expr

attr/expr/
value

SW

POM_enquiry_minus

attr/expr

attr/expr/
value

SW

POM_enquiry_divide

attr/expr

attr/expr/
value

SW

POM_enquiry_multiply

attr/expr

attr/expr/
value

SW

POM_enquiry_substr

attr/expr

value

SW

POM_enquiry_upper

attr/expr

null

SW

POM_enquiry_lower

attr/expr

null

SW

POM_enquiry_ascii

attr/expr

null

SW

POM_enquiry_concat

attr/expr

POM_enquiry_ltrim

attr/expr

null

SW

POM_enquiry_rtrim

attr/expr

null

SW

POM_enquiry_length

attr/expr

null

SW

POM_enquiry_is_null

attr/expr

null

POM_enquiry_is_not_null

null

POM_enquiry_uid_of

attr/expr
attr

null

POM_enquiry_cpid_of

attr

null

POM_enquiry_tonumber

attr

null

Server Customization Programmers Guide

4-69

ITK customization

Chapter 4

Right

POM_enquiry_todate

Left
attr

Where it
can be
used

null

POM_array_length_equals

attr

null

POM_array_length_not_equals attr

null

Operator

Note

SWH means [S]elect [W]here [H]aving clauses and [-] means the operator is
applied to the outer query.

Use of POM load by enquiry

The POM can load the objects returned by a query. This has a number of benefits:

If you want to load all the objects returned by a query, you can make just one call
which both executes the query and loads the objects.

The loading of objects is more efficient than a normal POM_load_instances (or

loadInstances in CXPOM) and results in fewer SQL trips.

To use this functionality:

1. Make sure all the objects you want returned are of the same class. The POM
does not support loading objects of different classes using this method.
2. Create the enquiry as described above ensuring you have only one SELECT
attribute, the puid of the class you want to load. You can order the results as
long as you are ordering by one of the attributes of the class you are loading.
3. Call the POM_load_instances_possible_by_enquiry function and pass in
the name of the enquiry and the class you want to load instances of. Output
values are two arrays of objects, one for the objects the POM was able to load
and the other for those that the POM failed to load because of Access Manager
rules or a consistency check failure.

Customize text and error messages

You can define your own customized text and error messages for display in
Teamcenter. Once they are defined, the messages can be displayed or reported in
Teamcenter and ITK-based utilities.
Note

Error messages report errors used in the ERROR_raise() functions.

1. Create a custom text message:

a. Name the nontranslatable resource file as custom-name_text.xml and the
translatable resource file as custom-name_text_locale.xml.
b.

Reference the nontranslatable resource file in the file tc_text.xml file as

follows:
<xi:include href="custom-name_text.xml"
parse="xml"/>

4-70

Server Customization Programmers Guide

PLM00074 J

ITK customization

c.

Reference the translatable resource file in the nontranslatable resource file

(custom-name_text_locale.xml) as follows:
<xi:include href="custom-name_text_locale.xml"
parse="xml"/>

custom-name must be unique to ensure the keys have a unique prefix. (For
an example, see the textsrv_text_locale.xml file.)
d. Add the nontranslatable custom messages to the
TC_USER_MSG_DIR\no_translation\custom-name_text.xml file.
e.

Add the translatable custom messages to the

TC_USER_MSG_DIR\language_locale\custom-name_text.xml file.
language_locale is the JAVA standard language name, for example, fr_FR,
en_US, ja_JP, zh_TW, and so on.

f.

Remove the shared memory backing store files pointed to by the

TC_SHARED_MEMORY_DIR environment variable.

2. Create a custom error message:

a. Define the symbol that represents the custom user error using the defined
base for user errors. This can be defined in your code file or in a dedicated
error header file, for example:
#define UE_MY_USER_ERROR (EMH_USER_error_base + 1)

b.

Copy the ue_errors.xml file from the

TC_ROOT\lang\textserver\language_locale directory to the
TC_USER_MSG_DIR\language_locale directories for each supported
language.

c.

Edit the copied files to include the new custom user error, for example:
<error id="1">This is the error message associated with the
custom error UE_MY_USER_ERROR. A parameter is noted
"%1$".</error>

d. Remove the shared memory backing store file.

There are 999 user-defined error numbers restricted to a specified range. The
emh_const.h file contains the EMH_USER_error_base constant. Include
the file in your code and use this constant to define your error numbers. This
minimizes upgrade issues if the range of user-defined error numbers changes.
Note

Make sure not to reuse an error code that already exists. Siemens
PLM Software recommends to use the error base, 919000, which is
reserved for customers (in the ue_errors.xml file).
Error message parameters are formatted in the error message
using the %1$ notation. There can be up to seven error message
parameters.

PLM00074 J

Server Customization Programmers Guide

4-71

ITK customization

Chapter 4

In earlier versions, custom error strings were stored in a UIH file. You
can convert UIH files to XML with the uih_to_xml utility, located in the
TC_ROOT\bin directory.
For additional information, see the Utilities Reference.

ITK customization for Teamcenter applications

You can use ITK APIs to create and manipulate objects used by Teamcenter
applications.

Classification
You can use ITK APIs to create and manipulate Classification objects.
Creating custom logic for autocomputing Classification attribute values
Using Classification you can autocompute values for attributes that are marked as
Autocomputed.
For more information, see the Classification Administration Guide.
The custom logic for autocomputing is divided into three parts:

include statements

Main program
This program is used when creating the Business Modeler IDE extension
definition so that it becomes the entry point for the computation logic. This
program registers all the attribute dependencies and computing functions.

Computing functions
These functions contain the logic for manipulating attributes. Each function is
registered against an autocomputed attribute, and once registered, is called
directly from Teamcenter during normal execution.

1. Register autocomputed attributes.

Each autocomputed attribute must be registered. This registration is a one-time
process and needs to happen during the initialization. For each autocomputed
attribute, the registration data consists of two parts:

Contributing dependency attributes

Computing function

For registering attributes, use the following API:

ICS_auto_compute_register_attrs (
const char*
class-id,
const char*
view-id,
const int
num-attrs,
ICS_auto_compute_attr_t*
auto-compute-attrs,
logical
override-flag
)

4-72

Server Customization Programmers Guide

PLM00074 J

ITK customization

Following are the values in the example.

Value

Description

class-id

Specifies the class ID for the attribute.

view-id

Specifies the view ID for the attribute. (If a

view exists, it may be left blank.)

num-attrs

Specifies the number of attributes on which

this attribute depends.

auto-compute-attrs

Specifies the dependency structure containing

the dependency attribute IDs and a pointer
to the compute function. (The structure is
explained below.)

override-flag

Specifies the flag to indicate overriding of the

parent class registration.

An attribute dependency structure is a new data structure specifically developed

for the autocomputation of attributes:
typedef struct ICS_auto_compute_attr_s
{
int auto_compute_attr_id;
ICS_auto_compute_function_t auto_compute_function;
int num_attr_deps;
int attr_deps[ICS_MAX_CLASS_ATTR_SIZE];
}ICS_auto_compute_attr_t;

2. Implement computing functions.

For each autocomputed attribute, register some computing function. Typically,
perform the following steps using the provided APIs:
a. Read the values and properties of attributes.
b.

Take the result and execute custom attribute manipulation logic.

c.

Use the manipulated values and properties for the autocomputed attributes.

To allow this interaction with the attributes, use the following ITK APIs:

ICS_auto_compute_get_attr_value
This API retrieves the values for the given attribute.

PLM00074 J

Parameters

Description

attributeId

Specifies the attribute ID to retrieve value

for.

valueCount

Specifies the number of values for this

attribute.

values

Specifies the array of values for this

attributes.

formats

Specifies the array of formats for values of

this attribute.

Server Customization Programmers Guide

4-73

Chapter 4

ITK customization

Parameters

Description

unit

Specifies the array of units for values of this

attribute.

ICS_auto_compute_set_attr_value
This API sets the values for the given attribute.

Parameters

Description

attributeId

Specifies the attribute ID to set value for.

valueCount

Specifies the number of values for this

attribute.

values

Specifies the values for this attributes.

unit

Specifies the units for values of this

attribute.

ICS_auto_compute_get_attr_prop
This API retrieves a specific property for the given attribute.

Parameters

Description

attributeId

Specifies the attribute ID to retrieve

property for.

property_name

Specifies the property name to retrieve.

values

Specifies the property value.

ICS_auto_compute_set_attr_prop
This API sets a specific property for the given attribute.
Parameters

Description

attributeId

Specifies the attribute ID to set property for.

property_name

Specifies the property name to set.

values

Specifies the property value.

If you install sample files using the Teamcenter Environment

Manager (TEM), a sample PLM XML file is available for import in the
TC_ROOT\sample\in-CLASS\auto_compute directory of your installation.
This file provides an example of creating custom logic for a Classification
attribute.
For a detailed description of APIs, see the Integration Toolkit Function Reference.
Note

4-74

The Integration Toolkit Function Reference is not available in PDF

format. It is available only in the Teamcenter HTML Help Collection.

Server Customization Programmers Guide

PLM00074 J

ITK customization

Teamcenter mechatronics process management

You can use ITK APIs to create and manipulate Teamcenter mechatronics process
management (Mechatronics Process Management) objects.
Mechatronics Process Management fundamental objects
Teamcenter provides objects to work with functional representations, logical
representations and electrical representations of electromechanical products.
Component

Objects

Electrical components

Functionality
FunctionalityRevision

Signals

Signal
ProcessVariable

Electrical interfaces

GDE
GDEOccurrence
Network_Port
Connection_Terminal

Electrical connections

PSConnection
Network
Connection
GDELink

Routes

RouteNode
RouteSegment
RouteCurve
RoutePath
RouteLocation
RouteLocationRev

Allocations

Allocation
AllocationMap

For more information about these objects, see the Wiring Harness Design Tools
Integration Guide.
The following relationships allow you to associate fundamental objects:

PLM00074 J

Implemented By

Realized By

Connected To

Routed By

Server Customization Programmers Guide

4-75

ITK customization

Chapter 4

Device To Connector

Assigned Location

Associated System

Redundant Signal

Process Variable

For more information about these relationships, see the Wiring Harness Design
Tools Integration Guide.
To control the behavior of objects and actions on those objects, you can set the
following preferences:

Connected_ToRules

Implemented_ByRules

Realized_ByRules

APN_absolute_path_name_separator

GDEOcc_display_instance_num_for_types

TC_releasable_logical_types

HRN_node_referenced_component_relation_secondary

HRN_associated_part_relation_secondary

Keep these preferences in mind when developing your ITK code. For more
information about these preferences, see the Wiring Harness Design Tools
Integration Guide.
Object model
The Mechatronics Process Management object model provides capabilities for
representing all aspects of an electromechanical product. In the context of wire
harness modeling, Mechatronics Process Management specifically provides objects
to work with the functional representation, logical representation, and electrical
representation of electromechanical products. Modeling an electromechanical
product in Teamcenter involves working with the objects highlighted in the
Teamcenter mechatronics process management object model. This model is depicted
in the following figure.

4-76

Server Customization Programmers Guide

PLM00074 J

ITK customization

Mechatronics Process Management object model

Harness model support
The classes implemented to support wire harness data include routing and topology
related classes such as Route, Node, Segment, and b_curve to capture the path
information associated with connections and devices implementing the connections.
Routes, segments and nodes contain a definition of the 2D or 3D routing topology
associated with connections, devices or other domain specific physical objects such as
wires. A route is defined as a course taken from a starting point to a destination. A
route defines the course either by using one or more segments or a set of nodes in
combination with curve objects, which define the shape of the route.
All route objects, such as segments, nodes, and curves, do not have any meaning
outside the context of the top level assembly (in other words, a BOM view revision).
Mechatronics Process Management API modules
There are five ITK modules that you can use to customize objects to fit your needs:

PSCONN
This module provides functions that allow you to manipulate connectivity data.
The functions are defined in the psconnection.h header file.

PLM00074 J

Server Customization Programmers Guide

4-77

ITK customization

Chapter 4

GDE
This module provides functions that allow you to manipulate item elements. The
functions are defined in the gde.h header file.

SIGNAL
This module provides functions that allow you to manipulate signals. The
functions are defined in the pssignal.h header file.

ROUTE
This module provides functions that allow you to manipulate routes. The
functions are defined in the route.h header file.

ALLOC
This module provides functions that allow you to manipulate allocations. The
functions are defined in the allocation.h header file.

There are example using some of the functions in the modules in the API use
examples section. You can also find sample programs using these modules in the
\samples\mechatronics directory. For more details about the modules, see the
Wiring Harness Design Tools Integration Guide. For more details about the modules
functions, see the Integration Toolkit Function Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

You can use PLM XML to export and import data used by the Mechatronics Process
Management API modules. For more information, see the Wiring Harness Design
Tools Integration Guide or the PLM XML/TC XML Export Import Administration
Guide. You can also use the modules in a Multi-Site Collaboration environment.
For more information, see the Wiring Harness Design Tools Integration Guide or
Multi-Site Collaboration Guide.
API use examples
Consider the climate control system illustrated in the following figure. This system
can be used in several contexts, such as an automobile or home. The system and
its contents have particular meaning when used in specific contexts. Similarly,
all Mechatronics Process Management objects have real meaning when used in
specific contexts.

4-78

Server Customization Programmers Guide

PLM00074 J

ITK customization

Climate control system

Creating functionality and functionality revision objects
Functionality objects are represented by a type of an item.
The following example creates a functionality object and its corresponding
functionality revision object:
nt ifail = ITK_ok;
tag_t rev = NULLTAG;
tag_t item = NULLTAG;
ifail = ITEM_create_item( item_id,
item_name,
item_type,
item_revision_id,
&item,
&rev );
if (ifail != ITK_ok)
return ifail;
else
{
ifail = ITEM_save_item (item);
if (ifail != ITK_ok)
return ifail;
else
ifail = AOM_refresh(item, false);
}

Creating interface port objects

An interface port must be created and added to the functionality before new ports
can be defined. Interface ports are represented by a type of item element object.
The following example creates an interface port:
int
ifail
= ITK_ok;
tag_t gde_obj
= NULLTAG;
ifail = GDE_create ( gde_name,
gde_description,
gde_type,
&gde_obj );
if (ifail != ITK_ok)
return ifail;
else
{
ifail = AOM_save (gde_obj);
if (ifail != ITK_ok)
return ifail;
else

PLM00074 J

Server Customization Programmers Guide

4-79

Chapter 4

ITK customization

ifail = AOM_refresh(gde_obj, false);

}

Defining ports for a functionality object

Once interface ports are created, you can define ports for a functionality by attaching
them to a revision of a functionality for a given context (view). All ports under a
given item revision are tracked using an item element BOM view revision (BVR)
associated with the item revision.
The following example creates the item element BVR and attaches the interface
port to the functionality revision:
int
ifail
= ITK_ok;
tag_t gde_bvr
= NULLTAG;
tag_t gde_occ
= NULLTAG;
/* Create GDEBVR under a functionality revision */
ifail = ITEM_rev_create_gde_bvr ( rev, view_type_tag, &gde_bvr);
if (ifail != ITK_ok)
return ifail;
/* Attach the interface port to functionality revision by creating GDEOccurrence
*/
ifail = GDE_create_occurrence ( gde_bvr,
gde_obj,
view_type_tag,
occurrence_type, /* can use NULLTAG */
quantity,
instance_no,
&gde_occ);
if (ifail != ITK_ok)
return ifail;
else
{
ifail = AOM_save (gde_bvr);
if (ifail != ITK_ok)
return ifail;
else
ifail = AOM_refresh(gde_bvr, false);
}

Creating connections
Assume that you have used the APIs described above to create Functionality_0
containing Functionality_1 and Functionality_2. Functionality_1 has Port1 and
Functionality_2 has Port2 (as shown in the following figure). You must connect Port1
and Port2 in a given context.
Note

4-80

Connections are only valid for the given context. A separate connection
call is required to associate a connection object with ports for each usage
of a connection occurrence.

Server Customization Programmers Guide

PLM00074 J

ITK customization

Functionality connections
The following example creates connections for Port1 and Port2:
int
ifail
= ITK_ok;
tag_t window = NULLTAG;
/* Create BOMWindow to display the product structure of Functionality_0 */
ifail = BOM_create_window ( &window );
if (ifail != ITK_ok)
return ifail;
ifail = BOM_set_window_pack_all ( window, TRUE );
if (ifail != ITK_ok)
return ifail;
ifail = BOM_set_window_top_line ( window,
functionality_1_item,
functionality_1_rev,
NULLTAG,
&topline );
/* Each of the components that used in the structure will be represented as a BOMLine.
We need to get BOMLines for Port1 and Port2 so that we can use them in making connection.
*/
tag_t *childs = NULL;
int count = 0;
ifail = BOM_line_ask_all_child_lines(topline, &count, &childs);
if (ifail != ITK_ok)
return ifail;
/* Look for BOMLines for Port1 and Port2 */
tag_t gdelineType = NULLTAG;
ifail = TCTYPE_find_type (GDELine, (const char*)0, &gdelineType);
if (ifail != ITK_ok)
return ifail;
tag_t line_type_tag = NULLTAG;
tag_t line_for_port1_port2[2];
int
line_found = 0;
char* object_name = NULL;
for ( int inx =0; inx < count; inx++ )
{
ifail = TCTYPE_ask_object_type(childs[inx], &line_type_tag);
if (ifail != ITK_ok)
return ifail;
if (line_type_tag == gdelineType)
{
ifail = AOM_ask_value_string ( childs[inx], "bl_line_name", &obj_name );
/* Get the BOMLine for Port1 and Port2 */
if (! strcmp(obj_name, Port1) || ! strcmp(obj_name, Port2))
{
line_for_port1_port2[line_found] = childs[inx];
line_found++;
if (line_found >= 2)
break;
}
}
}
/* Create connection */
if (line_found > 0)
{

PLM00074 J

Server Customization Programmers Guide

4-81

Chapter 4

ITK customization

ifail = PSCONN_connect (connection_id,

connection_name,
connection_type,
connection_rev,
line_found,
line_for_port1_port2,
&connection_line_tag);
}

Listing connections
The following example lists ports that are connected by a connection:
Ifail = PSCONN_list_connected_gdes( connection_line_tag,
&gde_line_count,
&gde_line_tags);

Disconnecting ports from a connection

This function does not delete the connection object, but it does break the linkage
between the ports and connection objects.
The following example disconnects all ports from a connection:
Ifail = PSCONN_disconnect ( connection_line_tag);

Removing specific ports from a connection

The following example removes Port1 from the connection:
tag_t port_to_remove[*];
int
port_count;
port_to_remove[0] = line_for_port1;
port_count = 1;
ifail = PSCONN_remove_from_connection ( connection_line_tag,
port_count,
port_to_remove);

Creating process variables

Process variables are a type of item element. The following example creates a
process variable:
int
ifail
= ITK_ok;
tag_t process_variable_obj
= NULLTAG;
ifail = GDE_create ( process_variable_name,
process_variable_description,
ProcessVariable,
// Type of gde
&process_variable_obj );
if (ifail != ITK_ok)
return ifail;
else
{
ifail = AOM_save (process_variable_obj);
if (ifail != ITK_ok)
return ifail;
else
ifail = AOM_refresh(process_variable_obj, false);
}

4-82

Server Customization Programmers Guide

PLM00074 J

ITK customization

Creating signals
Signal objects are created using the SIG_create_signal API as shown in the
following example:
int ifail = ITK_ok;
tag_t rev = NULLTAG;
tag_t signal = NULLTAG;
ifail = SIG_create_signal( signal_id,
signal _name,
signal _type,
signal _revision_id,
&signal,
&rev );
if (ifail != ITK_ok)
return ifail;
else
{
ifail = ITEM_save_item (signal);
if (ifail != ITK_ok)
return ifail;
else
ifail = AOM_refresh(signal, false);
}

Creating signal-process variable associations

Signals are sometimes generated due to a variation of the system variable, such as
temperature or pressure. In the climate control example in the API use examples
topic, the signal is generated due to a variation in car temperature compared to a
preset value.
To represent this variation, a signal can be associated with a process variable of
the current context using the SIG_set_signal_pvariable function, as shown in
the following example:
ifail = ITK_ok;
ifail = SIG_set_signal_pvariable( signal_line_tag, process_variable_line_tag );
if( ifail != ITK_ok )
return ifail;

In this example, the signal_line_tag and process_variable_line_tag tags

represent the signal line and process variable line in the current context.
The SIG_set_signal_pvariable function requires that you set the
SIG_pvariable_rules preference to the object type that is being passed in as
secondary.
Establishing signal associated system relations
For a signal to have meaning, it must be identified with the system (associated
systems) that processes the signal and its purpose. The purpose defines the role a
system plays in the existence of the signal within the specified context. The standard
Teamcenter installation provides the following set of roles:

PLM00074 J

Source

Target

Transmitter

Server Customization Programmers Guide

4-83

Chapter 4

ITK customization

To set a source, target, or transmitter associated system programmatically, set

the corresponding preference for that associated system to include the type of the
secondary object being passed in to the function.
In the climate control example in the API use examples topic, the electrical
signal is generated by the TempMeasure functionality and consumed by the
TempRegulator functionality.
Note

The association between signal and associated system is only valid in the
specified context.

The following example associates the signal to the system:

int ifail = ITK_ok;
ifail = SIG_set_associated_system( signal_line_tag,
asystem_line_tag,
role,
&relation_tag );
if( ifail != ITK_ok )
return ifail;
Note

Similar to signals, process variables also have associated systems that

generate, consume, or transmit the process variable. The association
between process variable and associated system in a given context can be set
using the SIG_set_associated_system function.

Removing the relation between a signal/process variable and associated system

The association between a signal or process variable and an associated system in a
specified context can be removed using the SIG_unset_associated_system or the
SIG_unset_associated_systems function.
You should use the SIG_unset_associated_system function to remove all
associated system relations, corresponding to valid associated system roles, between
a signal or process variable line tag and an associated system line tag. This function
does not take multiple inputs for the signal or process variable line or the associated
system line.
You should use the SIG_unset_associated_systems function to remove
associations between a signal or process variable line tag and one or more secondary
BOM lines for a specific role that is passed in to the function. If one or more of the
secondary BOM lines passed in is invalid, or if an association does not exist between
the signal or process variable line and one or more of the secondary BOM lines, that
secondary line is added to a failedLines array output variable, and the function
processes the next secondary BOM line. You must pass a valid non-null role in the
role argument (for example, source, target, or transmitter).
The following example removes all associated system relations between a signal
and associated system:
int ifail = ITK_ok;
ifail = SIG_unset_associated_system( signal_line_tag, asystem_line_tag );
if( ifail != ITK_ok )
return ifail;

In this example, the signal_line_tag and asystem_line_tag arguments represent

the tags of the signal and associated system lines in a specified context.
The following example removes a specific associated system relation corresponding
to the source role between a signal and secondary lines:

4-84

Server Customization Programmers Guide

PLM00074 J

ITK customization

int ifail = ITK_ok;

logical hasFailures = false;
int numFailedLines = 0;
tag_t *failedLines = 0;
ifail = SIG_unset_associated_systems( priLineTag, numSecondaries,
secondaries, source, &hasFailures, &numFailedLines, &failedLines );
if( ( ifail != ITK_ok ) || ( hasFailures ) )
{
// process the failures
}

In this example, the priLineTag and secondaries arguments represent the tags
of the primary signal or process variable line and the secondary associated system
lines, respectively. The failedLines argument is an output array that holds the
failed secondary lines. The hasFailures argument is a logical argument that is set
to true if failures exist. The numFailedLines argument is an integer that holds
the number of failed removals.
Maintaining redundant signals
To maintain proper system function, it is sometimes necessary to maintain duplicate
signals in a specific context.
For example, in the climate control example in the API use examples topic, it is
essential to maintain a redundant TempFunctionality functionality in the rear of
the car that generates exactly the same signal as the functionality in the front of the
car. This maintains proper functioning of the climate control system.
Redundant signals are identified by associating duplicate signals with the primary
signal using the SIG_set_redundant call, as depicted in the following example:
int ifail = ITK_ok;
ifail = SIG_set_redundant_signal( primary_signal_line_tag,
redundant_signal_line_tag,
&relation_tag );
if( ifail != ITK_ok )
return ifail;
Note

There can be multiple redundant signals for a given signal based on the
criticality of the function being regulated.

Removing redundant signals

Redundant signals associated with a primary signal in a given context can be
removed using the SIG_unset_redundant_signal call, as shown in the following
example:
int ifail = ITK_ok;
ifail = SIG_unset_redundant_signal( primary_signal_line_tag,
redundant_signal_line_tag );
if( ifail != ITK_ok )
return ifail;

In this example, redundant_signal_line_tag is the line tag of the redundant

signal in the given context.
Setting signal values
Signals represent changes in the values of process variables; therefore, they carry
values for the regulation of the process variables. These values can be fixed, for

PLM00074 J

Server Customization Programmers Guide

4-85

ITK customization

Chapter 4

example 5 volts, or they can be a range, for example 510 volts. Because the value
can vary from one revision to another, signal values are set on the signal revision
objects using the SIGREV_set_signal_value function, as shown in the following
example:
int ifail = ITK_ok;
ifail = SIGREV_set_signal_value( signal_revision, value );
if( ifail != ITK_ok )
return ifail;

In this example, signal_revision is the tag of the signal revision object and value is
the double value to be set on the signal revision.
Setting signal characteristics
Signals represent process variables that vary in a given context; therefore, the
value of the signal differs to represent the change. This variation in signal value
with respect to the process variable is defined as a signal characteristic, which is
represented either as an equation or as a human-readable text on each signal
revision.
Note

Teamcenter does not interpret signal characteristics on a signal revision.

This is assumed to be part of the Teamcenter implementation at a given site.

The following example sets signal characteristics on a signal revision:

int ifail = ITK_ok;
ifail = SIGREV_set_signal_characteristics( signal_revision, characteristics );
if( ifail != ITK_ok )
return ifail;

Setting signal line values

Values on signal revision objects represent a ranges or expected values that the
signal is expected to generate. The actual value of a signal exists within a specific
context. For example, in the climate control example in the API use examples topic,
the value on the signal generated by the TempMeasure functionality depends on
the exact condition (temperature) inside a car. In addition, the value generated by
the TempMeasure functionality is different if the climate control system is used in
a room or in a truck, rather than in a car.
The following example sets signal line values:
int ifail = ITK_ok;
ifail = SIG_set_signal_line_value( signal_line_tag, value );
if( ifail != ITK_ok )
return ifail;

In this example, signal_revision represents the tag of the signal revision object and
value represents the double value to be set on the signal revision.
Limitations

4-86

Configuration and effectivity rules are not supported by GDELine.

There are no precise and imprecise forms of GDELine.

Server Customization Programmers Guide

PLM00074 J

ITK customization

Allocations
Allocations represent a mapping from one view in a product structure to another
view. You use allocations to create separate views of a product, then map the views
to each other. You can model a purely functional structure that is independent of
the parts that eventually realize the functions. With careful analysis, you can use
independent groups of parts to design different products with the same functional
and logical models. Allocations allow you to link the actual parameters on physical
parts to the requirements on the functional and logical models. This permits you
to verify the components in the product are valid for their proposed purpose. For
more information about allocations, see the Wiring Harness Design Tools Integration
Guide.
Object model
There are two allocation object models. The first, shown in the following figure, is for
persistent allocations stored in the database.

Allocation persistent object model

The second model, shown in the following figure, is for run-time allocations in a
window with lines that associate source BOM lines with target BOM lines.

PLM00074 J

Server Customization Programmers Guide

4-87

Chapter 4

ITK customization

Allocation run-time object model

Preferences
You can carry forward all allocations created in the context of an allocation map
revision when it either revised, copied, or saved as a different revision by setting the
ALLOC_map_copy_allocations preference.
You can use a preference to control the cardinality of source and targets to be
associated. For example, you can enforce a Network_Port object to participate in
one-to-one relations only with the ALLOC_source_target_cardinality preference.
The ALLOC_Source_Occurrence_Types and
ALLOC_Target_Occurrence_Types preferences specify a list of components
for a given allocation type that can participate as source and target components,
respectively.
The ALLOC_Product_Representation_Types preference limits the view
subtypes that can be used for creating allocations for a given allocation map type.
The ALLOC_Group_Allocation_Types preference limits the type of allocations
that can be used for creating allocations for a given allocation map type. For
example, you can specify that the Allocation_One subtype of Allocation be created
only in association with the AllocationMap_one subtype of AllocationMap.

4-88

Server Customization Programmers Guide

PLM00074 J

ITK customization

For more information about these preferences, see the Preferences and Environment
Variables Reference.
API functions
There are two kinds of allocation API functions: persistent and run-time. The
allocation run-time model provides a simplified run-time abstraction of the
allocation-related persistent object model. The run-time model includes an allocation
window that contains allocation lines that associate source BOM lines with target
BOM lines. Each allocation line shows attributes derived from a persistent allocation
object.
For more information about the available functions, see the Integration Toolkit
Function Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Example
You can write a user exit to check if an allocation is complete and correct. The
criteria for that are dictated by the business logic of your enterprise. Through these
user exits, you can perform the validity checks from the user interface.
You can register a method against the following user exit messages:

ALLOC_is_allocation_complete_msg

ALLOC_is_allocation_correct_msg

For example, to register a custom method that defines the business logic against
the user exit messages:
METHOD_register_method("AllocationLine", ALLOCATION_is_allocation_complete_msg,
&my_complete_allocation, NULL, &my_method))

This custom method returns TRUE if the custom conditions are satisfied, otherwise
it returns FALSE. The conditions you implement are based on your requirements.
For example, to define the correctness of an allocation if and only if the source
components are of a particular type:
static int my_configure_allocations (METHOD_message_t *message, va_list args)
{
int iFail = ITK_ok;
// Extract the Object.
Customer specific business logic
//return ITK_ok;
}

By default, an allocation is correct if it has a source and/or a target component.

Embedded Software Manager
Embedded software is a critical component within electronics devices. It undergoes
upgrades and enhancements independent or part of electronic devices. The
Embedded Software Manager (ESM) in Teamcenter manages the software
components and their dependencies as well as the functional and physical
components and their dependencies in an integrated product development
environment. The ESM delivers four critical components to handle software

PLM00074 J

Server Customization Programmers Guide

4-89

Chapter 4

ITK customization

management: the embedded software manager itself, embedded software explorer,

the signal manager, and the signal explorer. The ITK functions corresponding to
these four components are broadly divided into the ESM_ functions and the SIG_
functions. For more information about the ESM, see Embedded Software Solutions
Guide.
The ESM is installed as an additional component during the Teamcenter installation
process and requires a separate license. For more information, see either the
Installation on Linux Clients Guide or Installation on Windows Clients Guide.
Before using ITK to customize the ESM, ensure its related preferences are set to
the correct software categories, types, and dataset types. For more information, see
the Preferences and Environment Variables Reference.
The following table lists the ESM module functions you can use to customize the
Embedded Software Manager. These functions support the management of software,
processor, and their dependencies.
For more information about these functions, see the Integration Toolkit Function
Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Function

Definition

ESM_is_processor

Given a BOM line tag, checks whether it is a

processor BOM line.

ESM_is_gateway

Given a processor BOM line tag, checks whether

it is a gateway processor BOM line.

ESM_is_software

Given a BOM line tag, checks whether it is a

software BOM line.

ESM_associate_processor_to_ Given a processor BOM line and an array of

software
software BOM lines, associates processor and
software using the Embeds relation. To save
the associations, save the BOM window.
ESM_associate_processor_to_ Given a gateway processor BOM line and
processor
an array of other processor BOM lines that
are accessed through the gateway processor,
associates the processors in the array with
the gateway processor using the GatewayOf
relation. To save the associations, save the BOM
window.

4-90

ESM_associate_software_to_
software

Given a software BOM line and an array of

software BOM lines, associates software using
the Dependent On relation. To save the
associations, save the BOM window.

ESM_remove_processor_to_
software_association

Given a processor BOM line and an array of

software BOM lines, removes the Embeds
relation association of the processor and software
lines. To save the associations, save the BOM
window.

Server Customization Programmers Guide

PLM00074 J

ITK customization

Function

Definition

ESM_remove_processor_to_
processor_association

Given a gateway processor BOM line and an

array of associated processor BOM lines, removes
the GatewayOf relation association between
the processor lines. To save the associations,
save the BOM window.

ESM_remove_software_to_
software_association

Given a software BOM line and an array of

software BOM lines, removes the Dependent
On relation association of the software lines. To
save the associations, save the BOM window.

ESM_ask_embedded_
software_of_processor

Given a processor BOM line, gets an array

of software BOM lines that are associated to
processor with the Embeds relation.

ESM_ask_gateway_of_
processor

Given a processor BOM line, gets an array of

gateway processor BOM lines that are associated
to it with the GatewayOf relation.

ESM_ask_processors_
accessedby_processor

Given a gateway processor BOM line, gets an

array of processor BOM lines that are associated
to it with the GatewayOf relation.

ESM_ask_dependent_
software_of_software

Given a primary software BOM line, gets an

array of secondary software BOM lines that are
dependent on the primary software.

ESM_ask_software_used_by_ Given a secondary software BOM line, gets an

software
array of primary software BOM lines that are
used by the secondary software.
The following table lists the SIG module functions you can use to customize the
Embedded Software Manager. These functions support the management of signals
and their dependencies.
For more information about these functions, see the Integration Toolkit Function
Reference.
Note

PLM00074 J

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Function

Definition

SIG_set_associated_systems

Sets the secondary lines as an associated system

based on the input role to the primary signal
or process variable line. This function requires
you to set the appropriate preference to the
correct type for the association to be created
for that type. If the preference exists, but does
not have a value, the corresponding association
is not created. For more information about
the ESM preferences, see the Preferences and
Environment Variables Reference.

Server Customization Programmers Guide

4-91

ITK customization

Chapter 4

Function

Definition

SIG_unset_associated_
systems

Removes associations between a signal or process

variable line tag and one or more secondary
BOM lines for a specific role passed in to the
function. If one or more of the secondary BOM
lines passed in is invalid, or if an association does
not exist between the signal or process variable
line and one or more secondary BOM lines, that
secondary line is added to a failedLines array
output variable, and the function processes the
next secondary BOM line. You must pass a valid
non-null role in the role string argument.

SIG_ask_signal_sources

Finds all the sources of the signal or message

line tag using the associated_system relation.

SIG_ask_signal_targets

Finds all the targets of the signal or message

line tag using the associated_system relation.

SIG_ask_signal_transmitters Finds all the transmitters of the signal or

message line tag using the associated_system
relation.
SIG_ask_device_sources

Finds all the source devices that transmit

messages or signals to the target device,
represented by linetag. This function uses
the underlying associated_system relation
between source and message or signal.

SIG_ask_device_targets

Finds all the targets devices that the device,

represented by linetag, transmits messages or
signals to. This function uses the underlying
associated_system relation between target
and message or signal.

SIG_ask_device_transmitted_ Finds all the messages or signals that are

signals
transmitted by a source device, represented
by linetag. This function uses the underlying
associated_system relation between source
and message or signal.
SIG_ask_device_received_
signals

Finds all the messages or signals that are

received by a target device, represented by
linetag. This function uses the underlying
associated_system relation between target
and message or signal.

You might want execute some of the following tasks programmatically:

Associate a processor with the software to be installed on it.

Associate processors with a gateway processor.

Associate software with other software dependent on it.

The following sample is a code snippet that does the following:

4-92

Takes a set of input BOM lines.

Server Customization Programmers Guide

PLM00074 J

ITK customization

Separates the gateway processor from the other processors.

Creates the gateway relationship.

Queries the relationship through the ESM_ask_ functions.

Gets the processors that are accessed through this gateway processor.

Removes the gateway associations.

Note

All other create, ask, and removal methods follow a similar coding pattern.
// Get the gateway and the processor lines from the list of lines passed in
tag_t gateway_processor_line = NULLTAG;
for( jnx = 0 ; jnx < numBOMLines; inx++ )
{
If ( ESM_is_gateway( inputbomlines[inx] )
gateway_processor_line = inputbomlines[inx];
else
{
If ( ESM_is_processor( inputbomlines[inx] )
{
processorLines[num_processor_lines] = inputbomlines[inx[;
num_processor_lines++;
}
}
}
/// associate the gateway and the processor lines
int stat = ESM_associate_processor_to_processor(
gateway_processor_line, num_processor_lines,
processorLines, &hasFailures, &numFailedLines, &failedLines);
for( inx = 0; inx < numFailedLines; inx++)
{
//Perform any custom error reporting
}
.
// next, we query for all processors accessed through this gateway// in this example, if numFailedLines was 0, the lines in
// processorLines above, will match the lines in
// accessed_processor_lines. Note that the array is not a sorted list
stat = ESM_ask_processors_accessedby_processor(
gateway_processor_line, &num_accessed_lines,
&accessed_processor_lines);
// Now we remove the associations between the processors and gateway
stat = ESM_remove_processor_to_processor_association(
gateway_processor_line, num_processor_lines, processorLines,
&hasFailures, &numFailedLines, &failedLines);

Product structure management

You can customize the product structure management functionality. There are two
modules associated with managing product structure:

Bill of Materials (BOM) module

The BOM module operates at the highest level; below the Structure Manager
user interface and above the PS module. It is oriented toward the presentation
of and interaction with product structure and encompasses the application of
configuration rules.

PLM00074 J

Server Customization Programmers Guide

4-93

ITK customization

Chapter 4

The BOM module is used for general operations, such as creating reports and
editing structure. It pulls together information from items, item revisions, BOM
view revisions and occurrences to present them as entries in a bill of materials.

Product Structure (PS) module

The PS module handles product structure operations at a lower level. It is also
responsible for the creation and manipulation of the basic structure objects (in
other words, BOM views and occurrences).
This module is most useful for large scale import of structure data into
Teamcenter or batch operation to update specific structure attributes where the
overhead of building up the full presentation of BOM-related information is
not required.

Bill of Materials (BOM) module

The BOM module is intended to give a consistent interface to the separate elements
that make up a line in a bill of materials. The design assumes that you have a BOM
window (which may be a printed report or displayed in a window) showing a bill of
materials made up of BOM lines. Each BOM line shows attributes derived from
items, item revision, occurrences and so on; along with some attributes belonging to
the BOM line itself. None of the individual objects the line represents (for example,
is_packed) are shown.
The names of the attributes give a clue as to which object they are derived from; you
can ignore that and treat them all as BOM line attributes. Although some attributes
are standard and listed in the bom_attr.h file, others are defined at run time (for
example, the note types on occurrences) and have to be found by inquiry.
The BOM module is described in two parts. The first part is for those who want to
produce a report listing a bill of materials. Following this is more detail describing
other functions needed for editing the bill and using more complicated facilities.
Producing a report
When producing a report, you must follow this procedure:
1. Create a BOM window.
The first thing you have to do is create a BOM window with a call to the
BOM_create_window function. The window may need some default settings.
For example, default lines are not packed and the configuration rule is the users
default one (if defined); otherwise it is the latest with any status.
Note

To change the configuration rule, you have to ask for the configuration
rule and then use the CFM ITK routines to modify it.

2. Define what to display.

Call the BOM_set_window_top_line function to define what the window
displays. This routine takes an item, item revision, and BOM view as arguments,
but most of these can be NULLTAG tags.
If the item revision is non-null, that particular revision is used. If it is
NULLTAG, a non-null item must be given and the configuration rule is used to
determine the revision.

4-94

Server Customization Programmers Guide

PLM00074 J

ITK customization

If the BOM view is non-null, it is used. Otherwise, the oldest one is used.
Note

Until multiple views are used, there is never more than one BOM view
in an item.

3. Find children for a BOM line.

Given a BOM line, you can find its children using the
BOM_line_ask_child_lines function. To find attributes of a line, you have to
call the BOM_line_ask_attribute_xxx function, where xxx depends on whether
you are asking about a tag, string, integer, logical or double. Before you can
call the ask_attribute function, however, you need to find the attribute ID for
the attribute you want to ask about.
4. Find an attribute ID.
If you know what attribute you want, you can use the
BOM_line_look_up_attribute function to translate its name to an ID.
Otherwise, you have to use the BOM_line_list_attributes function to find all
available ones and then work out which you want.
Attributes themselves have attributes of their own. They have a name, user
name, mode, read-only flag and an internal/external flag. The name is unique
and is what you use to look up an attribute. The user name is not necessarily
unique and is intended as a suitable name to describe the attribute. The mode
is a value defined in the bom_attr.h file and states if the attribute is a string,
int, or some other kind.
The read-only flag is true if the attribute cannot be changed. For example,
assume that the name attribute is built up from the item ID, revision ID and so
on. As such, the name cannot be changed. To change the name attribute, you
have to change the item ID directly.
Note

Because an attribute is not read-only does not mean you can set that
attribute on any particular line. If the line shows released data, the
set_attribute fails.

The internal/external flag is intended to say whether the attribute was defined
internally (and might be expected to be available the next time you run the
program) or externally (by virtue of reflecting an occurrence note type; so it may
not exist in some other run of the program).
If you are looking for data that is not available as an attribute (for example, a
dataset in the item revision of some BOM line), you can use the tag attributes
(item revision tag, in this case) to find the underlying object. Next, use ITK
queries on the object
Note

A simple program displaying all attributes should ignore tag attributes

as being meaningless to display.

Occurrence sequencing
The single-level structure of an item revision is made up of a collection of links from
a BOM view revision (the parent) to the items which are components of the assembly
(the children). These links are known as occurrences.

PLM00074 J

Server Customization Programmers Guide

4-95

Chapter 4

ITK customization

An occurrence represents the usage of an item or an item revision within the product
structure of a parent. You can distinguish between different kinds of occurrences in
the BOM by referring to occurrence sequencing.
For detailed information about the BOM and product structure (PS) functions, see
the Integration Toolkit Function Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Editing the BOM

If you want to edit the bill of materials you can use the BOM_line_cut,
BOM_line_add and BOM_line_replace functions. Be aware that the latter two
use the same NULLTAG argument options as the BOM_set_window_top_line
function.
If a BOM window is set to display pending edits and you made specific pending
edits to a BOM line, you can remove those edits from the selected BOM line with
the BOM_line_revert_pending_edits function or all of those pending edits in the
BOM window with the BOM_window_revert_all_pending_edits function.
The BOM_line_set_precise function implements the option precise user interface
command. You can use the BOM_line_set_attribute_xxx functions to change those
attributes that are not read-only.
If you have edited structure by direct PS ITK calls, you can re-synchronize the BOM
world by calling the BOM_update_pse function. When you have finished your
edits you must call the BOM_save_window function to save any changes made
in that bill of materials.
Note

The BOM_save_window function calls underlying PS routines to save

whatever data the BOM module knows needs saving. It is possible to mix
BOM and PS calls within the same program, but you must ensure that you
call PS to save any change you make that the BOM does not know of.

The other functions do not affect the stored data; they only affect the display (in this
case, the results of the BOM_line_ask_child_lines function).
Restructuring the BOM
You can add a level with the BOM_line_insert_level function. The levels
below the new level keep their associated data. You can remove a level with the
BOM_line_remove_level function. If you remove a level, options associated with
the removed level are moved up to the level above. Variant conditions associated
with the removed level are merged into their children. If you want to split a BOM
line, use the BOM_line_split_occurrence function. The new level initially
copies all associated data from the original level, including notes and variant
conditions. The total quantity after the split equals the original quantity. The
BOM_line_move_to and BOM_line_copy functions move and copy the BOM line
to a new place in the structure, respectively. Absolute occurrences are preserved
during all restructuring operations.

4-96

Server Customization Programmers Guide

PLM00074 J

ITK customization

Using global alternates

A global alternate part is interchangeable with another part in all circumstances,
regardless of where the other part is used in the product structure. A global
alternate applies to any revision of the part and is independent of any views. Parts
and their global alternates are related only in a single direction. Use the following
functions to manage global alternates of a single item, such as listing, adding,
removing, and setting the preferred global alternate:

ITEM_list_related_global_alternates
Lists related global alternates.

ITEM_add_related_global_alternates
Adds global alternates.

ITEM_remove_related_global_alternates
Removes global alternates.

ITEM_prefer_global_alternate
Makes the specified global alternate the preferred global alternate for the
specified item.

ITEM_ask_has_global_alternates
Checks if the specified item has any global alternates.

Packing the BOM

Packing is controlled at the window level by a default flag. If you call the
BOM_line_pack or BOM_line_unpack function on a given line, however, the
results of later calls to ask_child_ lines on its parent change. By default, lines
are packable if they have the same item revisions and the same find numbers. By
calling the BOM_set_pack_compare function, you can supply a different compare
function. This function applies session-wide; it is not window-specific.
Note

The interactive Structure Manager assumes that all packed lines show the
same find number. If the user changes the find number, it sets all of the
lines to that number. If you change this function, Structure Manager might
not work correctly.

Sort functions
The BOM_line_ask_child_lines function lists the lines in some order determined
by a sort function. The default function sorts by find number and then by item name.
The BOM_set_window_sort_compare_fn function can be used to change this
function on a per window basis.
Sample BOM program
The following code shows how the BOM ITK functions can be used:
/* An example program to show a list of a bill of materials using the BOM module
@<DEL>*/
#include <stdio.h>
#include <string.h>

PLM00074 J

Server Customization Programmers Guide

4-97

Chapter 4

#include
#include
#include
#include
#include
#include
#include
#include

ITK customization

<stdlib.h>
<unidefs.h>
<itk/mem.h>
<tc/tc.h>
<tccore/item.h>
<bom/bom.h>
<cfm/cfm.h>
<ps/ps_errors.h>

/* this sequence is very common */

#define CHECK_FAIL if (ifail != 0) { printf ("line %d (ifail %d)\n", __LINE__, ifail);
exit (0);}
static int name_attribute, seqno_attribute, parent_attribute, item_tag_attribute;
static void initialise (void);
static void initialise_attribute (char *name, int *attribute);
static void print_bom (tag_t line, int depth);
static void print_average (tag_t top_line);
static void find_revision_count (tag_t line, int *count, int *total);
static void double_find_nos (tag_t line);
static int my_compare_function (tag_t line_1, tag_t line_2, void *client_data);
/*-------------------------------------------------------------------------------*/
/* This program lists the bill under some given item (configuring it by latest+working).
It then doubles all the find numbers and re-lists it by descending find number
order. It then counts how many lines there are in the bill and the average number of
revisions of the items in that bill.
It never actually modifies the database.
Run this program by:
<program name> -u<user> p<password>
*/
extern int ITK_user_main (int argc, char ** argv )
{
int ifail;
char *req_item;
tag_t window, window2, rule, item_tag, top_line;
initialise();
req_item = ITK_ask_cli_argument("-i=");
ifail = BOM_create_window (&window);
CHECK_FAIL;
ifail = CFM_find( "Latest Working", &rule );
CHECK_FAIL;
ifail = BOM_set_window_config_rule( window, rule );
CHECK_FAIL;
ifail = BOM_set_window_pack_all (window, true);
CHECK_FAIL;
ifail = ITEM_find_item (req_item, &item_tag);
CHECK_FAIL;
if (item_tag == null_tag)
{ printf ("ITEM_find_item returns success, but did not find %s\n", req_item);
exit (0);
}
ifail = BOM_set_window_top_line (window, item_tag, null_tag, null_tag, &top_line);
CHECK_FAIL;
print_bom (top_line, 0);
double_find_nos (top_line);
/* we will not use
ifail = BOM_save_window (window);
because that would modify the database
*/
/* now lets list the results sorted the other way */
ifail = BOM_create_window (&window2);
CHECK_FAIL;
ifail = BOM_set_window_config_rule( window2, rule );
CHECK_FAIL;
ifail = BOM_set_window_pack_all (window, false);
/* the default, but lets be explicit */
CHECK_FAIL;

4-98

Server Customization Programmers Guide

PLM00074 J

ITK customization

ifail = BOM_set_window_sort_compare_fn (window2, (void *)my_compare_function, NULL);

CHECK_FAIL;
ifail = BOM_set_window_top_line (window2, item_tag, null_tag, null_tag, &top_line);
CHECK_FAIL;
printf ("================================================\n");
print_bom (top_line, 0);
print_average (top_line);
ITK_exit_module(true);
return 0;
}
/*-------------------------------------------------------------------------------*/
static void print_bom (tag_t line, int depth)
{
int ifail;
char *name, *find_no;
int i, n;
tag_t *children;
depth ++;
ifail = BOM_line_ask_attribute_string (line, name_attribute, &name);
CHECK_FAIL;
/* note that I know name is always defined, but sometimes find number is unset.
If that happens it returns NULL, not an error.
*/
ifail = BOM_line_ask_attribute_string (line, seqno_attribute, &find_no);
CHECK_FAIL;
printf ("%3d", depth);
for (i = 0; i < depth; i++)
printf (" ");
printf ("%-20s %s\n", name, find_no == NULL ? "<null> : find_no);
ifail = BOM_line_ask_child_lines (line, &n, &children);
CHECK_FAIL;
for (i = 0; i < n; i++)
print_bom (children[i], depth);
MEM_free (children);
MEM_free (name);
MEM_free (find_no);
}
/*-------------------------------------------------------------------------------*/
static void double_find_nos (tag_t line)
{
/* just to demonstrate modifying the bill */
int ifail;
char *find_no;
int i, n;
tag_t *children;
ifail = BOM_line_ask_attribute_string (line, seqno_attribute, &find_no);
CHECK_FAIL;
/* Top bom lines have no find number, and others may also not */
if (find_no[0] != \0)
{
char buffer[100];
sprintf (buffer, "%d", 2 * atoi (find_no));
ifail = BOM_line_set_attribute_string (line, seqno_attribute, buffer);
if (ifail != ITK_ok)
{
char *child_name;
ifail = BOM_line_ask_attribute_string (line, name_attribute, &child_name);
CHECK_FAIL;
printf ("==> No write access to %s\n", child_name);
MEM_free (child_name);
}
else
{
CHECK_FAIL;
}

PLM00074 J

Server Customization Programmers Guide

4-99

Chapter 4

ITK customization

MEM_free (find_no);
}
ifail = BOM_line_ask_child_lines (line, &n, &children);
CHECK_FAIL;
for (i = 0; i < n; i++)
double_find_nos (children[i]);
MEM_free (children);
}
/*-------------------------------------------------------------------------------*/
static void print_average (tag_t top_line)
{
int count = 0, total = 0;
find_revision_count (top_line, &count, &total);
if (count <= 0)
{
printf ("impossible error has happened!\n");
}
else
{
printf ("lines in bill : %d\naverage revisions of each item : %d\n", count, total
/ count);
}
}
/*-------------------------------------------------------------------------------*/
static void find_revision_count (tag_t line, int *count, int *total)
{
/* A function to demonstrate going from BOM tags to other classes
*/
/* In this case, we get the Item tag for the BOM line, and then use it for an */
/* ITEM call. For a complete list of standard attributes see bom_attr.h, or
*/
/* use a BOM_list_attributes call to find all current attributes (new note
*/
/* types define new attributes)
*/
int ifail;
tag_t item_tag, *revisions, *children;
int i, n, revision_count;
char* item_id;
ifail = BOM_line_ask_attribute_tag(line, item_tag_attribute, &item_tag );
CHECK_FAIL;
/* the simplest example call I can think of:
*/
/* count how many revisions of this Item there are */
ifail = ITEM_list_all_revs (item_tag, &revision_count, &revisions);
CHECK_FAIL;
MEM_free (revisions);
(*count)++;
(*total) += revision_count;
ifail = BOM_line_ask_child_lines (line, &n, &children);
CHECK_FAIL;
for (i = 0; i < n; i++)
find_revision_count (children[i], count, total);
MEM_free (children);
}
/*-------------------------------------------------------------------------------*/
static int my_compare_function (tag_t line_1, tag_t line_2, void *client_data)
{
/* returns strcmp style -1/0/+1 according to whether line_1 and line_2 sort <, = or > */
char *seq1, *seq2;
int ifail, result;
ifail = BOM_line_ask_attribute_string (line_1, seqno_attribute, &seq1);
CHECK_FAIL;
ifail = BOM_line_ask_attribute_string (line_2, seqno_attribute, &seq2);
CHECK_FAIL;
if (seq1 == NULL || seq2 == NULL)
result = 0;
else
result = strcmp (seq2, seq1); /* Doing a reverse sort */
/* note: the default sort function compares Item names if the find numbers sort
equal but we will not show that here

4-100

Server Customization Programmers Guide

PLM00074 J

ITK customization

*/
MEM_free (seq1);
MEM_free (seq2);
return result;
}
/*-------------------------------------------------------------------------------*/
static void initialise (void)
{
int ifail;
/* <kc> exit if autologin() fail */
if ((ifail = ITK_auto_login()) != ITK_ok)
fprintf(stderr,"Login fail !!: Error code = %d \n\n",ifail);
CHECK_FAIL;
/* these tokens come from bom_attr.h */
initialise_attribute (bomAttr_lineName, &name_attribute);
initialise_attribute (bomAttr_occSeqNo, &seqno_attribute);
ifail = BOM_line_look_up_attribute (bomAttr_lineParentTag, &parent_attribute);
CHECK_FAIL;
ifail = BOM_line_look_up_attribute (bomAttr_lineItemTag, &item_tag_attribute);
CHECK_FAIL;
}
/*-------------------------------------------------------------------------------*/
static void initialise_attribute (char *name, int *attribute)
{
int ifail, mode;
ifail = BOM_line_look_up_attribute (name, attribute);
CHECK_FAIL;
ifail = BOM_line_ask_attribute_mode (*attribute, &mode);
CHECK_FAIL;
if (mode != BOM_attribute_mode_string)
{ printf ("Help, attribute %s has mode %d, I want a string\n", name, mode);
exit(0);
}
}

Occurrences
An occurrence represents the usage of an item or an item revision within the product
structure of a parent. You can distinguish between different kinds of occurrences in
the BOM and product structure.
For more information about occurrence functions, see the Integration Toolkit
Function Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Options and variations

The basic concepts behind options and variations are that options are used to
customize the BOM and variant expressions that reference these options at run time.

Expressions
Expressions are built as a parse-tree of variant expressions. A collection of these
expressions is held in a variant expression block. The same mechanism is used to
attach variant conditions to an occurrence and attach variant declarations to an
item revision. The restriction is that only appropriate types of expressions may
be attached to each parent. With an occurrence, the variant expression block
may only contain one expression and must be a LOAD-IF type of expression.
With an item revision, many types of expressions may be used to declare an
option, set a value or apply an error check.

PLM00074 J

Server Customization Programmers Guide

4-101

ITK customization

Chapter 4

Range of Allowed Values

Each variant expression contains an operator, a left operand and a right operand.
Options are defined to belong to some item, but the range of allowed values is
stored in option revisions. In most cases the bottom of an expression tree is an
option, but the declare operator references an option revision to identify the
range of allowed values current assembly option.

Restrictions
Options are only enumerated values. Expression trees only evaluate to logical
or integer values.

If you want to print a report showing variant conditions on a BOM or ignore BOM
lines that are not selected by the current option values, use ITK enquiries for BOM
line values rather than trying to evaluate variant expression trees. The ITK routines
documented here are very low-level routines that are intended to be used to create
variant conditions when building a BOM.
Variant operator values are defined in the bom_tokens.h file. The
BOM_variant_op_rhs_is_string value can be added to other operators to allow a
string to be used as the right operand. In most cases the right operand should be an
integer value that is stored as a text string containing decimal digits.
Operators
The following table lists each variant expression operator, the type of left and right
operands allowed in that expression, and a brief description.
Note

4-102

The operator names in the following table are truncated for convenience.
The full name is the operator name in the following table prefixed
with BOM_variant_operator_. For example, declare in the table is
BOM_variant_operator_declare.

Operator

Left operand Right operand

type
type

declare

option revision NULLTAG

If this option has not yet been

declared for this BOM, then
declare it as this revision.

assy_uses

option

NULLTAG

Not used.

default

option

expression or
string

Sets the option to the specified

value unless the option has
already been set. The value
is an integer index into the
allowed range of enumerated
values.

assign

option

expression or
string

Sets the option to the

specified value unless it has
been previously set. Returns
an error if the option already
has a different value.

Server Customization Programmers Guide

Description

PLM00074 J

ITK customization

PLM00074 J

Operator

Left operand Right operand

type
type

error_if

expression

string

Used to implement error

checks. Reports the string as
an error if expression is true.

if

do-expression

condition
expression

Evaluates do-expression if
condition-expression is true.
This is used to implement
derived values by making the
do-expression set a default
value.

is_equal

expression

expression

Compares the two

expressions. Typically the
first expression is an option
and the second a string in
order to verify that the option
is set to the specified value.

not_equal

expression

expression

Compares the two

expressions. Typically the
first expression is an option
and the second a string in
order to verify that the option
is not set to the specified
value.

and

expression

expression

Evaluates the logical AND of

the two expressions.

or

expression

expression

Evaluates the logical OR of

the two expressions.

load_if

NULLTAG

expression

The top operator of the

expression in a variant
condition attached to an
occurrence.

comment

NULLTAG

string

Not used.

rule_set

option

expression or
string

Used by variant rule objects

to store option-value pairs.
This should not be used in
any other context.

brackets

NULLTAG

expression

Placeholder for marking

sub-expressions which
the user would like to be
bracketed. This operator has
no effect on the evaluation
of the overall expression, it
is only used when displaying
the expression in text form.

Description

Server Customization Programmers Guide

4-103

Chapter 4

ITK customization

Run-time options
Once the assembly has been built to include variations data, option values can be
used to determine what parts of the assembly to display at run time. Options can
be listed and set from a specified window using the BOM_window_ask_options
and BOM_window_set_option_value functions, respectively. If the desired option
is known, but it is not known whether it has been previously referenced, use the
BOM_window_find_option function instead of the BOM_window_ask_options
function. The following code shows an example of listing and setting option values:
#include <string.h>
#include <unidefs.h>
#include <tc/tc.h>
#include <bom/bom.h>
void panic();
void error(const char* message);
void set_option(tag_t w, const char *option, const char *value)
{
/* Sets an option to the specified value in Structure Manager window w. */
tag_t *options, *option_revs;
tag_t found_option, found_option_rev;
int *indexes;
int i, n;
if (BOM_window_ask_options(w, &n, &options, &option_revs) != ITK_ok) panic();
for (i = 0; i < n; i++)
{
char *name, *description;
tag_t owning_item;
logical found;
if (BOM_ask_option_data(options[i], &owning_item, &name, &description)!= ITK_ok)
panic();
found = (strcmp(name, option) == 0);
MEM_free(name);
MEM_free(description);
if (found) break;
}
if (i == n) error("option not used in this window");
found_option = options[i];
found_option_rev = option_revs[i];
MEM_free(options);
MEM_free(option_revs);
if (BOM_list_option_rev_values(found_option_rev, &n, &indexes) != ITK_ok) panic();
for (i = 0; i < n; i++)
{
char *opt_value;
logical found;
if (BOM_ask_option_rev_value(found_option_rev, indexes[i], &opt_value)!= ITK_ok)
panic();
found = (strcmp(opt_value, value) == 0);
MEM_free(opt_value);
if (found) break;
}
if (i == n) error("option not allowed to have that value");
/* now do the work */
if (BOM_window_set_option_value(w, found_option, indexes[i]) != ITK_ok) panic();
MEM_free(indexes);
}

Option creation and declaration

When creating a new option with the BOM_create_option function, it is necessary
to declare the option revision against an item revision. You can both create and
declare an option with a single call to the BOM_new_option function. To declare

4-104

Server Customization Programmers Guide

PLM00074 J

ITK customization

an existing option against a different item revision, call the BOM_declare_option

function.
BOM variant rule
The BOM variant rule is a run-time object that represents the list of options and
their values in a BOM window. In general, you can ignore this object and use the
BOM_window_ variant functions to get and set option values.
However, this object is for creating multiple BOM variant rules against a BOM
window; although only one is actually applied to the BOM window at any one time.
This can be used to set multiple option values without reconfiguring the entire BOM
after each set operation, although option defaults and rule checks are still triggered.
Then, once all options have been set, the BOM variant rule can be applied to the
BOM window.
The BOM variant rule supports an ITK interface that is almost identical to the
BOM window variant functions for getting and setting options and their values.
A BOM windows current BOM variant rule can be obtained by a call to the
BOM_window_ask_variant_rule function.
Variant expression manipulation
In an attempt to simplify Variant Expression interaction at the ITK level, some
high-level concepts have been introduced. A Variant Clause List can be used to
create and edit conditional variant expressions (for example, Engine = 1.6 AND
Gearbox = manual). These conditional expressions can then be used to create
IF type Variant Expressions (for derived defaults, rule checks, and occurrence
configuration) using the simple BOM_variant_expr_ ITK calls.
Variant clause list
Variant clause lists are used to store conditional variant expressions in a more easily
understood (and edited) format. For example, the condition:
"Engine = 1.6 OR Engine = 1.8 AND Gearbox = manual"

would be represented in a clause list as:

"Engine = 1.6"
"OR Engine = 1.8"
"AND Gearbox = manual"

In other words, each clause is a simple condition and a join operator (AND or OR).
Clauses may be added (anywhere in the list), deleted, moved, or queried. Individual
clauses within the list are identified by their position. The first clause is at position
0, the second at position 1, and so on.
Brackets are supported by variant clause lists. To add brackets around a section of a
clause list, call the BOM_variant_clause_toggle_brackets function and pass it
the array of clause positions to be contained within the brackets. For example, to
place brackets around the Engine = 1.8 AND Gearbox = manual section of the
previous example, pass in an array containing the positions 1 and 2.

PLM00074 J

Server Customization Programmers Guide

4-105

Chapter 4

ITK customization

Note

To add brackets around a clause list section that contains more than two
clauses, pass in the positions of the first and last clauses in the section. The
other positions are ignored. The array mechanism is used, in preference to
only supplying first and last position arguments, to simplify user interface
implementations by allowing you to simply pass in the list of currently
selected clauses, rather than expecting you to filter the selection list down to
just the first and last.

Modular variants
If you work with modular variants, you must take a different approach in your ITK
code. For example, if you want to create a BOM selected option set, set the option
values, and then apply the set, you:
1. Ask for the selected option set from a BOM line:
BOM_line_ask_sos( bl, &sos )
Note

There are two kinds of option sets: a run-time selected option set and a
persistent stored option set kept in the database.

2. Get its contents to set its options and values:

BOM_sos_ask_entries( sos, entry_count, options, paths )

3. Set the value for each option. In this call, the function sets option1 with the
value of Economy:
BOM_sos_set_entry_string( sos, options[ 0 ], "", "Economy", 4 )

4. Apply the set:

BOM_sos_apply( sos, true )

If you want to create a stored option set in the database and then read it, you:
1. Ask for the selected option set from the BOM line:
BOM_line_ask_sos ( bomline1, bomsos )

2. Create a variant configuration object. The first variable is given if you have
a classic variant rule:
BOM_create_variant_config ( NULLTAG, 1, { bomsos }, bom_variant_config )

3. Set the option and values as well as the mode:

BOM_sos_set_entry_string ( bomsos, opt, "", "value1",
BOM_option_set_by_user )
BOM_sos_set_entry_logical ( bomsos, opt1, "", true,
BOM_option_set_by_user )

Then create a stored option set in the database from the BOM variant
configuration:
BOM_sos_db_create("bomsos1", bom_variant_config, sos1)

4. Read the saved stored option set contents from the database:
BOM_sos_db_contents(sos1, count, items, options, optionTypes, valueTypes,
howSet, values)

4-106

Server Customization Programmers Guide

PLM00074 J

ITK customization

If you want to read and load the contents of the stored option set saved in the
database, you:
1. Ask for the selected option set from the BOM line:
BOM_line_ask_sos ( bomline1, bomsos2 )

2. Create a variant configuration object:

BOM_create_variant_config ( NULLTAG, 1, { bomsos2 }, bom_variant_config2 )

3. Read the stored option set from the database:

BOM_sos_db_read ( sos1, bom_variant_config2 )

4. Get the value of the option in the stored option set:

BOM_sos_ask_entry_display ( bomsos2, opt, "", value, howset )

5. Apply the variant configuration:

BOM_variant_config_apply ( bom_variant_config2 )

Exporting configured assemblies to NX

You can configure a product structure with revision rules and variants,
and then export the configured structure to NX in native format. Use the
BOM_export_configured_nx_assembly function in the BOM module.
For more information about this function, see the Integration Toolkit Function
Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

BOM Compare functions

BOM Compare provides a powerful method of comparing different BOMs, BOM
revisions, and configurations of BOMs.
Scope of compare
BOM Compare operates on the contents of two BOM windows. This means that it
picks up the configuration rules of the BOM windows from which the compared BOM
lines were taken. If you want to compare different configurations of the same BOM,
first set up two BOM windows with the required configurations.
By default, the BOM_compare function compares everything below the supplied
BOM lines right down to the bottom of the BOM. It automatically loads any required
structures.
If a you want to prevent a compare from loading the components of a
specific structure, set the stop flag of the structures BOM line, using the
BOM_line_set_stop function. The stop flag can be cleared using the
BOM_line_clear_stop function. In Structure Manager-based compares, the stop
flags are set on all visible leaf nodes and collapsed structure nodes.
Defining a compare
A BOM Compare is defined by two components:

PLM00074 J

Server Customization Programmers Guide

4-107

ITK customization

Chapter 4

Compare descriptor

BOM Compare mode

Compare descriptor
The compare descriptor is a list of attributes (referred to as compare elements to
differentiate them from POM attributes) that are used as the basis of the compare.
Although most compare elements are simply be properties (and are handled
automatically by the compare engine), you can compare based on nonproperty
elements by defining methods. You can also use methods to customize the compare
behavior for awkward properties (for example, quantity, which is described in this
section).
Compare elements can be generally divided into two distinct groups: primary
elements and aggregate elements (theres a third group: display elements, which
is described in this section). The key difference between these two groups is that
primary elements define different entities, while aggregate elements are combined
for multiple instances of the same entity. For example, the compare functionality
before version 8 (when expressed in version 8 terms) defined item ID as a primary
element and quantity as an aggregate element. This meant that BOM lines that
had the same item ID were bundled together for the purposes of compare and
their quantities were added together. In other words, 1 BOMLine with qty 2 was
equivalent to 2 BOMLines with qty 1.
In the following code example, the compare descriptor uses the bl_occurrence
(occurrence thread tag) property, the bl_item property, the bl_quantity property,
and the Torque (an occurrence note) property.
BOM Compare mode
The BOM Compare mode is a uniquely named object that combines a compare
descriptor and a BOM traversal order. The BOM traversal order defines which
BOM lines are fed into the compare engine, and in what order. The BOM Compare
supports three traversals: single-level, multilevel, and lowest level. A single
descriptor can be shared between multiple compare modes.
The following code shows a single-level compare which is best suited for an
occurrence-based compare:
int define_compare_mode()
{
int ifail;
tag_t desc;
ifail = CMP_find_desc("example desc", &desc);
if (ifail != ITK_ok)
return ifail;
if (desc == NULLTAG)
{
ifail = define_compare_desc(&desc);
if (ifail != ITK_ok)
return ifail;
}
ifail = BOM_compare_define_mode(
"example mode",
BOM_compare_singlelevel, /* from bom_tokens.h */
desc,
/* from above */
false,
/* not shown UI - irrelevant*/
false,
/* no autopack - only multi-level needs this */
true
/* virtual unpack - copes with packed bomlines */

4-108

Server Customization Programmers Guide

PLM00074 J

ITK customization

/* All occurrencebased compares need this

);
if (ifail != ITK_ok)
{
/* If it was previously defined, return success */
if (ifail == BOM_duplicate_bom_compare_mode)
{
EMH_clear_errors();
return ITK_ok;
}
/* otherwise report failure */
return ifail;
}
return ITK_ok;

*/

}
int define_compare_desc(tag_t *desc)
{
tag_t new_desc;
tag_t new_element;
tag_t bomline_type;
/* Insert error handling here */
CMP_create_desc("example desc", &new_desc);
TCTYPE_find_type("BOMLine", NULL, &bomline_type);
/***** Primary Element : Occurrence Thread *****/
CMP_create_prop_element(
new_desc,
CMP_primary_element,
CMP_cache_sync,
/* Cache property values in native type */
NULL,
/* Do not define element name - will default to prop name */
false,
/* Show value of this property in output */
bomline_type,
/* Type to which prop belongs */
"bl_occurrence",
/* Name of property */
NULL,
/* No display prop - use real prop instead */
&new_element);
/***** Aggregate Element : Item *****/
CMP_create_prop_element(new_desc,
CMP_aggregate_element,
CMP_cache_sync,
NULL,
false,
bomline_type,
"bl_item",
"bl_item_item_id",
&new_element);
/***** Aggregate Element : Quantity *****/
CMP_create_prop_element(new_desc,
CMP_aggregate_element,
compareCacheSync,
"k_compare_qty",
false,
bomline_type,
"bl_quantity",
NULL,
&new_element);
/***** Aggregate Element : Torque Occ Note *****/
CMP_create_prop_element(new_desc,
CMP_aggregate_element,
CMP_cache_sync,
NULL,
false,
bomline_type,
"Torque",
NULL,
&new_element);
*desc = new_desc;
return ITK_ok;

PLM00074 J

Server Customization Programmers Guide

4-109

ITK customization

Chapter 4

For simple examples, defining a compare mode is relatively easy. You create your
descriptor and create a number of property elements against it. Then define your
mode, combining the descriptor with a traversal mode.
There are a number of features that are described as follows:

UI suppression
In the call to the BOM_compare_define_mode function, the fourth argument
is the mode UI display flag. This controls whether the UI should present this
compare mode in the Structure Manager BOM Compare dialog box. This is a
legacy setting and is now irrelevant because even if this was set to true, the UI
still would not show this mode in the dialog box. The UI dialog box is currently
hard coded to our standard pre-version 8 compare modes.

Auto pack
In the call to the BOM_compare_define_mode function, the fifth argument
defines whether multilevel compares should pack BOM lines as it goes along.
Auto pack is an attempt to allow the simplification of the presentation of the
results of multilevel compares where the primary compare elements match the
pack rule attributes. By default, the BOM line pack attributes are item ID and
find number. These are the primary attributes for the standard multilevel
compare as currently supported by the Structure Manager compare dialog box.
If you set this argument, set it to false.

Virtual unpack
In the call to the BOM_compare_define_mode function, the sixth argument
defines whether BOM lines should be temporarily unpacked during the compare.
If you are using bl_occurrence as one of your compare elements, set this flag to
true because packed BOM lines represent multiple occurrences. To gain access
to the individual occurrences, the compare must unpack the BOM line, pull out
the required data, and then repack, which is transparent to the end user. Why
is not this always switched on? The main limitation of virtual pack lies in the
BOM line property compare output. Normally, BOM compare sets a BOM line
property called Changes to display the actual changes that have happened to
3 or Rev A
B). If you are performing an
the BOM line (for example, Qty 2
occurrence-based compare, you might have two occurrences behind a packed
3). The
BOM line. One occurrence might have a change (for example, Qty 2
other occurrence might not have any change. In this situation, what should
3?
compare put in the Changes property of the BOMLine? Should it say Qty 2
Should it be empty? In reality, it says PACKED CHANGES, and expects the
user to manually unpack the BOM line to see to individual changes.
For non-UI compares, Siemens PLM Software recommends that the BOM
windows being compared have packing switched off.

Caching
In the calls to the CMP_create_prop_element function, the third argument
tells BOM Compare whether and how to cache property values. The
CMP_cache_sync setting means that the type of the cache should be
synchronized to the property value type. Setting this to CMP_cache_none
would disable caching of that property. The CMP_cache_auto setting is similar

4-110

Server Customization Programmers Guide

PLM00074 J

ITK customization

to CMP_cache_sync, but allows BOM Compare to make the final decision on the
cache type. This is important if you plan to use certain properties as aggregate
elements. For example, multiple tag elements cannot be aggregated into a tag
cache. Instead, they need a tag array cache type. The CMP_cache_auto setting
makes that decision for you. You can also manually specify the type of the cache,
but it is up to you to make sure that it is suitable for storing the property.

Element naming
In the calls to the CMP_create_prop_element function, the fourth argument
allows a user to specify the (internationalized) name by which this element is
known. If this is set to NULL, then the property name is used. Element naming
is primarily used for nonproperty compare elements, but can still be useful for
property elements where the property name is considered to be too verbose
for display in compare output. For example, with the bl_quantity property
you might want compare to output the more compact Qty rather than property
display name Quantity.

Element display suppression

In the calls to the CMP_create_prop_element function, the fifth argument
allows for the possibility that certain elements are useful for comparing, but not
good for displaying. For example, tag elements are great for comparing, but
because they are simply unsigned integers they have no meaning to end users.
This ties into display elements.

Element display aliasing

In the calls to the CMP_create_prop_element function, the eighth argument
provides a simplified version of the display elements concept. It allows an
unfriendly property to be replaced in the output stage with a more readable
one. In the example above, the bl_item property is used. This property is the
tag of the item. When displaying item changes to the user, you do not want to
show them item tags. Instead you would want to show them the item ID. To
do this, you could define bl_item_item_id as a display alias property of the
bl_item property element. Note that while you could use bl_item_item_id
as your compare element, the use of bl_item is much more efficient for two
reasons: it is an integer compare rather than a string compare, and bl_item
is a directly defined BOM line property while bl_item_item_id is indirected
through the item.

BOM Compare execution

The following code shows the code for a simple compare report:
tag_t compare;
int n_lines;
char **lines;
tag_t *cmp_items;
int i;
BOM_compare_create(&compare);
BOM_compare_execute(compare,
bomline1, bomline2,
"example mode",
BOM_compare_output_report);
BOM_compare_report(compare, &n_lines, &lines, &cmp_items);
for (i=0; i<n_lines; i++)
{

PLM00074 J

Server Customization Programmers Guide

4-111

Chapter 4

ITK customization

printf("%s\n", lines[i]);
/*
** BOMLines relating to this report line can be obtained via
** BOM_compare_list_bomlines(cmp_items[i], ...);
*/
}
AOM_delete(compare);

If you want the changes written to the BOM line Changes property,
just add the BOM_compare_output_bomline argument to
the BOM_compare_output_report argument in the call to the
BOM_compare_execute function.
Advanced definition concepts
There are several advanced definition concepts relating to display elements, output
order, and methods you must know to fully understand BOM Compare.
Display elements
In addition to primary and aggregate elements, BOM Compare can also support
display elements. These are elements that have no impact on the actual comparison.
Display elements are extra context data that is written as part of compare output.
This is just an advanced version of the element display aliasing concept. Aliasing is
limited in that it only works with property elements, and only a single alias property
can be defined. Display elements can be defined with methods, allowing nonproperty
data to be used. You can also define as many display properties as you want.
You can use the bl_item_item_id alias as a display alias for bl_item. If you want to
display the item name as well as the item ID, define a property display element for
the bl_item_object_name property in the descriptor, as shown in the following code:
CMP_create_prop_element(new_desc,
CMP_display_element,
CMP_cache_sync,
NULL,
false,
bomline_type,
"bl_item_object_name",
NULL,
&new_element);

Note that display elements are not aggregated. Teamcenter assumes that the
display element property value is constant across all BOM lines in a set. As such,
the display element value is simply pulled out of the first BOM line that the compare
engine finds.
Aggregate element uniqueness
With numeric elements, aggregation is easy: the numbers are just added together.
However, with string elements, aggregation is more difficult. The standard behavior
is simply to concatenate the strings into a comma separated list, in alphabetical
order. For example, A and B becomes A,B. If you aggregate A and A, it enforces
uniqueness (A + A = A).

4-112

Server Customization Programmers Guide

PLM00074 J

ITK customization

Element ordering modifier

Generally, string elements are sorted by simple alphabetic order. For example,
aardvark comes before albatross. However, you might want to store numeric
data in string attributes (for example, find number). In this case, alphabetic
order is not correct. For example, 20 comes before 3. To correct this, use the
CMP_set_prop_element_order function to set the element sort order to the
CMP_order_by_length_and_value setting.
Element application flags
The generic compare engine has no understanding of application concepts (BOM
Compare is an application built on top of the generic compare engine). However,
sometimes it is necessary for the application to store modifiers on the compare
descriptor. This is done using the application flags. Application flags are set by the
CMP_set_element_application_flag function. There are three application flags:

BOM_compare_display_aggregate

BOM_compare_stop_if_diff

BOM_compare_dont_report_adds

These are defined and documented in the bom_tokens.h file.

Object output order
If you have multiple primary elements, the order in which you define the elements
has an impact on the order in which objects are output in a report. Consider a
compare where you have two primary elements: Item Id and Find Number. Note
that these are the primary elements for two of the standard compare modes. If you
define the Item Id element before the Find Number element, then objects are
output sorted by Item Id and then by Find Number within that.
Consider three BOM lines with the following attributes:

item=widgetY, seqno=10

item=widgetX, seqno=20

item=widgetX, seqno=30

If you define your elements in the order (Item Id, Seq No), compare outputs the
lines in the order 2, 3, 1. This order is clearly not ideal. You normally would really
like the output to be in the same order in which it appears in Structure Manager (in
other words, 1, 2, then 3). To do this, simply reverse the order of element definition
to be (Seq No, Item Id). However, this affects the column output order, described
in the next section.
The use of find numbers introduces another feature. Consider this pair of BOM lines:

item=widgetX, seqno=20

item=widgetX, seqno=100

The order output should be 1 first and 2 second. Because find numbers are strings
and not integers, a string compare is performed and alphabetically 100 comes before

PLM00074 J

Server Customization Programmers Guide

4-113

ITK customization

Chapter 4

20. To get around this, mark the find number element (and any others that store
numbers as strings) as special with the CMP_set_prop_element_order function:
CMP_create_prop_element(new_desc, ..., &seqno_element);
CMP_set_prop_element_order(seqno_element, CMP_order_by_length_and_value);

This call tells the compare engine to sort by length, before sorting by value.
Column output order
By default, report output is generated with the columns in the same order as the
elements were defined in. In the previous section, the Find Number element is
defined ahead of the Item Id element to force the object output order to match
the Structure Manager display order. The side effect of this is that the report
columns are output in the (Seq No, Item Id) order. This does not match the
standard Structure Manager column display order where you expect to have
the item defined in the leftmost column, followed by the find number. You can
suppress the display of the find number element and define a display element
against the find number property. However, the better alternative is to define a
display order. To do so, create a tag array and populate it with the element tags
in the order that you want the columns to appear. Then pass that array into the
CMP_set_element_display_order function as shown in the following code:
tag_t seqno_element;
tag_t itemid_element;
tag_t elements[2];
CMP_create_prop_element(new_desc, ..., &seqno_element);
CMP_create_prop_element(new_desc, ..., &itemid_element);
elements[0] = itemid_element;
elements[1] = seqno_element;
CMP_set_element_display_order(new_desc, 2, elements);

Methods
When using property-based compare elements, the system provides default behavior
for comparing the property values. There are also some simple modifiers that can be
applied to handle certain special cases. If none of the modifiers do what you need,
you can write code that does exactly what you want and then register it against
the element.
There are six method types supported by the generic compare engine:

Compare object
This method must compare a given object against a given compare set and return
its opinion on whether that object belongs in that set. Note that this is just one
primary compare elements opinion. Other primary elements may disagree. All
primary elements must say yes for the object to be allowed into the set.

Compare aggregate
This method must compare the left and right sides of the given compare set and
return its opinion on whether the two sides are equivalent. Other aggregate
elements may disagree.

Cache
This method must update the elements cache when the supplied object is added
to the given side of the compare set.

4-114

Server Customization Programmers Guide

PLM00074 J

ITK customization

UIF name
This method returns the display name for this element.

UIF value
This method returns the display value for this element.

Free cache
One of the supported cache types is CMP_cache_pointer. This cache type
means that the user is taking responsibility for creating and managing the
cache. The generic compare engine simply maintains a void * pointer to the
cache. When using this cache type, you must supply a Cache method (to create
and update the cache), a UIF Value method (to return the display value for the
cache), and a Free Cache method. This Free Cache method is used to release
the memory allocated by the Cache method.

Nonproperty elements
This is the logical conclusion of the use of compare methods. A nonproperty element
is an element that is entirely driven through methods. It has no standard behavior.
This requires more effort, but allows maximum flexibility. For example, you could
perform a compare using elements that live entirely outside Teamcenter. It could
pull in data from a different database or from the Internet, which may take a
significant amount of time. If you plan to do this, Siemens PLM Software highly
recommends caching.
For an example of a nonproperty element, see the quantity elements in the
smp_user_bom_cmp.c file. While quantity is a BOM line property, Compare cannot
handle it directly because of the need to cope with special concepts like as required
and undefined (Structure Managers default quantity, in other words, one unit).
Advanced execution concepts
One of the advantages of the generic compare engine is that it provides access to
the internal data structures of the engine. This allows you to provide new output
destinations and formats directly off the raw data without having to post-process one
of the existing outputs. To use this, you must understand the internal data structure.
The top level object is the BOM Compare itself. This is the object that most of the
BOM Compare ITK functions deal with. A BOM Compare is described as having a
mode, an output destination, and two root BOM lines (often referred to as two sides
of the compare, left and right).
In single and lowest-level compare traversals, the BOM Compare object has a single
BOM Compare engine object. In multi-level compare traversals, the BOM Compare
has a tree of nested BOM Compare engines.
A BOM Compare engine contains a list of compare sets. Each compare set contains
two lists of BOM lines (one list for each side of the compare). Every BOM line in
a compare set has the same values for their primary elements. Compare sets are
capable of caching compared values. Primary and display elements are stored in a
single cache (per element) on the compare set. Aggregate elements require a cache
for each side of the compare.

PLM00074 J

Server Customization Programmers Guide

4-115

Chapter 4

ITK customization

To traverse this data structure, use the BOM_compare_visit_engine function, as

shown in the following code. This function traverses the internal data structure
invoking callbacks as it goes:
{
tag_t compare;
BOM_compare_create(&compare);
BOM_compare_execute(compare,
bomline1, bomline2,
"example mode",
0 /* No output - were going to do it ourselves */ );
BOM_compare_visit_engine(compare,
enter_engine,
leave_engine,
visit_set,
NULL /* User data pointer */ );
}
int enter_engine(tag_t bomcompareengine, tag_t compareset, int depth,
void *user_data)
{
tag_t root1, root2;
BOM_compare_ask_engine_root_bomlines(bomcompareengine, &root1, &root2);
printf("Entering compare engine %x, comparing BOMs %x and %x\n",
bomcompareengine, root1, root2);
/* You could use the CMP ITK to query the contents of the engine */
return ITK_ok;
}
int leave_engine(tag_t bomcompareengine, tag_t compareset, int depth,
void *user_data)
{
printf("Leaving compare engine %x\n", bomcompareengine);
/* You could use the CMP ITK to query the contents of the engine */
return ITK_ok;
}int visit_set(tag_t compareset, int depth, void *user_data)
{
/* You can use the CMP ITK to query the contents of the set */
printf("Compare set %x\n", compareset);
/* List which compare elements changed in this set */
int n;
tag_t *elements;
tag_t *bomlines;
int i;
CMP_ask_diff_elements(compareset, &n, &elements);
printf("Changed elements: ");
for (i=0; i<n; i++)
{
int element_type,
int priority,
int cache_type,
char *uif_name,
logical suppress_value;
char *lvalue;
char *rvalue;
CMP_ask_element_info(elements[i],
&element_type, &priority, &cache_type,
&uif_name, &suppress_value);
CMP_ask_element_value(compareset, CMP_LHS, elements[i], &lvalue);
CMP_ask_element_value(compareset, CMP_LHS, elements[i], &rvalue);
print(" %s has changed from %s to %s\n", uif_name, lvalue, rvalue);
MEM_free(uif_name);
MEM_free(lvalue);
MEM_free(rvalue);
}
MEM_free(elements);
/* List the bomlines on LHS of this set */

4-116

Server Customization Programmers Guide

PLM00074 J

ITK customization

CMP_ask_objects_in_set(compareset, CMP_LHS, &n, &bomlines);

printf(" Affected BOMLines on left hand side: ");
for (i=0; i<n; i++)
{
printf("%x ", bomlines[i]);
}
printf("\n");
MEM_free(bomlines);
return ITK_ok;
}

Performing a compare
The BOM Compare function BOM_compare_execute supersedes the older
BOM_compare call. The BOM_compare_execute function takes the tags of the
two BOM lines to be compared, along with the compare mode, and the output type,
and may optionally be given a compare context.
A compare context (gained from the BOM_compare_create function) is a slot into
which the results of a BOM Compare are put. Each one can only hold the results of
one compare. The BOM_compare_execute function can be told to use the default
compare context by passing in a null tag.
The default compare context is the one used by the user interface when running
BOM Compare from Structure Manager. If you use the default context while the
user interface might be using it, you clear any BOM Compare-related BOM line
highlighting and the ability to click on a report line and have the Structure Manager
select the correlate BOM lines. Merely using the default context causes this, even if
you do not ask for BOM line highlighting or text reports.
The standard mode names (BOM_std_compare_*_name) are available
as manifest constants from the bom_tokens.h file; the output selectors
(BOM_compare_output_*) are also available from the bom_tokens.h file. These
identifiers are used thus:
BOM_compare_execute( bomcomparecontext,
bomline1,
bomline2,
BOM_std_compare_single_level_name,
BOM_compare_output_bomline | BOM_compare_output_report );

For your own modes, you should establish and use your own manifest constants.
The standard compare modes are described in Structure Manager Guide, but you
can also declare new ones using the BOM_compare_define_mode function. To
define your own modes, you need to understand compare descriptors, which are part
of the generic compare engine.
The generic compare engine provides a way to compare two sets of objects, and
obtain the differences between the sets. Each set is divided into subsets containing
objects that match each other according to some user-defined criteria (primary keys).
If both sets each have a subset whose objects match by their primary keys, then the
objects within each subset are compared according to further user-defined criteria
(aggregate keys), and the results for this second compare between each correlate
pair of subsets are made available. A subset with no correlate subset is an addition
(or a deletion). The keys are specified with a compare descriptor.
For example, the functionality of BOM Compare has been re-implemented on top
of this generic engine. The two sets are the two sets of BOM lines for comparison;
the BOM lines are gathered into subsets according to item ID and optionally find

PLM00074 J

Server Customization Programmers Guide

4-117

ITK customization

Chapter 4

number, the primary keys, and where both sides of the compare has correlate
subsets, they are compared for quantity and revisions, the aggregate keys.
BOM Compare output
There are four forms of compare output available. The three original modes
are: user exits, BOM line, and report output. One is based on callbacks: the
BOM_compare_visit_engine function.
User exits
BOM Compare can call a number of user exit functions for both ITK- and Structure
Manager window-invoked compares. The user exits are:

USER_bom_cmp_start_report

USER_bom_cmp_enter_report

USER_bom_cmp_item_report

USER_bom_cmp_parent_report

USER_bom_cmp_exit_report

USER_bom_cmp_end_report

These user exit functions are always called by the Structure Manager
window-invoked compare. User exit output is optional for the ITK compare.
A number of ITK functions are available to allow the user exit functions to query
the compare results:

BOM_compare_list_bomlines

BOM_compare_ask_differences

BOM_compare_ask_qty

BOM_compare_ask_rev

BOM_compare_ask_seqno

This list of functions has been augmented by the generic compare functions that can
be applied to compare engines.
BOM line output
The following BOM line string property is set to contain the changes relating to
the particular BOM line:
bl_compare_change

The following two properties are additionally supported when the

BOM_compare_legacy_properties preference is true:
bl_quantity_change
bl_revision_change

If no differences are found for a particular BOM line, these properties are all blank.

4-118

Server Customization Programmers Guide

PLM00074 J

ITK customization

If the BOM_compare_legacy_properties preference is false or unset:

bl_compare_change
Contains the type of change for this line, either Added or one or more of the
Aggregate keys and key values for the BOM Compare Mode specified. For the
standard compare modes, the keys are Qty or Rev for quantity changes and
revision changes, respectively, so this property might look like, Qty:12 or
Rev:AB. This is a comma-separated list if more than one change occurs (for
example, both quantity and revision changes might look like Qty:12,Rev:AB).

If the BOM_compare_legacy_properties preference is true:

bl_compare_change
Contains the type of change, Added, Qty, or Rev for additions, quantity changes
and revision changes, respectively. This is a comma-separated list if more than
one change occurs (for example, both quantity and revision changes might look
like, Qty,Rev).

bl_quantity_change
Contains details of a quantity change (in other words, if Qty is a substring of
the bl_compare_change attribute). The change is stored as the two quantities
separated by an arrow (for example, 12).

bl_revision_change
Contains details of the revision change (in other words, if Rev is a substring of
the bl_compare_change attribute). The change is stored as the two revisions
separated by an arrow (for example, AB). If more than one revision of an item
exists in one of the BOMs then all the revisions are listed (for example, A,BC).

These properties may be cleared by calling the BOM_compare_clear function.

Note

If another compare is started (in a particular compare context) before the

previous one has been cleared, the old properties are automatically cleared.

Report output
Report output can be retrieved with the BOM_compare_report function. Note that
you must request report output when you call the BOM_compare_report function,
otherwise no report is generated.
The BOM_compare_report function returns the report as an array of formatted
character strings. The first string contains the column headers for the report. The
function also returns an array of compare items that match the report lines. These
compare items can be queried with the following functions:

BOM_compare_list_bomlines

BOM_compare_ask_differences

BOM_compare_ask_seqno

These functions have been augmented by the generic compare functions, as for
the user exits.

PLM00074 J

Server Customization Programmers Guide

4-119

ITK customization

Chapter 4

These functions are available only if the BOM_compare_legacy_report preference

is true:

BOM_compare_ask_qty

BOM_compare_ask_rev

BOM_compare_ask_seqno

Report lines that do not have matching compare items (for example, the column
header line) have their compare item listed as NULLTAG.
BOM Compare output suppression
BOM Compare output suppression allows the BOM Compare user exit functions
to switch off certain forms of compare output. For example, the default user exit
functions do not perform any useful actions. To prevent the Structure Manager
window-based compare from calling unnecessary user exit functions, the very first
user exit function (USER_bom_cmp_start_report) suppresses all other user exit
output, using the following line of code:
BOM_compare_suppress (line1, BOM_compare_output_userexit);

This suppression lasts for the duration of the current compare. The primary
intended use for this facility is if you wish to replace the BOM Compares internal
report window with your own report. To achieve this, you must write the user exit
functions to generate the report and display it in a window.
Once the report generation code has been written, the problem is how to control
which report window is displayed and when. You must first suppress the user exits
when report output was not selected in the BOM Compare dialog box:
If:
( (output & BOM_compare_output_report) == 0)
{
BOM_compare_suppress (line1, BOM_compare_output_userexit );
return ITK_ok;
}

You should now suppress the internal report window:

BOM_compare_suppress ( line1, BOM_compare_output_report );

There are many other potential uses for output suppression. Some further examples
are given in the USER_bom_cmp_start_report user exit source code.
BOM Compare visitor
After you run a compare (possibly without any output modes specified), you can ask
the system to walk the results tree, running user-supplied callbacks at each node.
This is very similar to the user exits system above, but because you pass in the three
callback functions instead of linking them into the user exits library, you can process
the results in various ways without needing to change the user exits library. The
callbacks have this correlation with the user exits:

4-120

The visit_set function is identical to the USER_bom_cmp_item_report

function, except that it has the extra user_data parameter - a void * parameter
supplied by your call to the BOM_compare_visit_engine function, pointing to
a structure you want your callbacks to build or maintain.

Server Customization Programmers Guide

PLM00074 J

ITK customization

The enter_engine function is analogous to USER_bom_cmp_parent_report

function. The following code makes that relationship explicit:

#include <unidefs.h>
#include <tc/tc.h>
#include <bom/bom.h>
#include <user_exits/user_exits.h>
int enter_engine( tag_t compare_engine, tag_t compare_set, int depth, void * user_data)
{
int itk_ret;
tag_t bomline1;
tag_t bomline2;
if ( ( itk_ret = BOM_compare_ask_engine_root_bomlines( compare_engine, &bomline1,
&bomline2) ) != ITK_ok )
return itk_ret;
return USER_bom_cmp_parent_report( bomline1, depth );
}

The leave_engine routine is called when all descendants of the latest active
parent announced through the enter_engine function have been visited. All
ordering is depth-first recursive, so each parent node is only reported once
immediately before all of its descendants, and once immediately after all of
its descendants. The following code counts the number of BOM lines (on the
left-hand or right-hand side) determined to be different by the compare:

/* Count BOM Lines in a compare, declares

extern int count_bomlines_in_compare ( tag_t compare_context, int cmp_side );
*/
#include <bom/bom.h>
#include <fclasses/cmp.h>
#include <tc/tc.h>
/* Structure for passing nominated side and current count around */
typedef struct
{
int count;
int side;
} count_bomlines_t;
/* Callback to add the number of objects for each set to user_data-count. */
/* Note, it would be trivial to put a loop in here to examine/modify
the BOM Lines in bomlines[], instead of merely counting them */
static int count_bomlines_visit_set ( tag_t compareset, int depth, void * user_data )
{
count_bomlines_t *data = (count_bomlines_t*) user_data;
int count;
tag_t *bomlines;
{
/* Ask compareset for the bomlines on the nominated side. (Im
only interested in how many there are, not what they are.) */
int itk_ret;
if ( ( itk_ret = CMP_ask_objects_in_set( compareset, data->side, &count,
&bomlines ) ) != ITK_ok )
return itk_ret;
}
data->count += count;
MEM_free( bomlines );
return ITK_ok;
}
/* Run over the BOM compare results passed in, and return the number of
BOM lines, or -1 on error. */
extern int count_bomlines_in_compare ( tag_t compare_context, int cmp_side )
{
count_bomlines_t results = { 0, cmp_side };
/* Use NULL for parent (engine) entry/exit callbacks, because
theyre not interesting here */
if ( BOM_compare_visit_engine( compare_context, NULL, NULL, count_bomlines_visit_set,

PLM00074 J

Server Customization Programmers Guide

4-121

ITK customization

Chapter 4

(void*) &results ) != ITK_ok )

{
return -1;
}
return results.count;
}

Product Structure (PS) module

The Product Structure (PS) ITK module manages the creation, manipulation and
storage of product structure data within Teamcenter.
Product structure in Teamcenter is represented by assembly items containing
links to component items which make up the assembly. The structure of items is
represented in BOM view objects. The links to component items are known as
occurrences.
The PS ITK module covers the creation of BOM views and BOM view revisions for
items and item revisions, the creation and modification of occurrences to reference
the component parts of an assembly, and the attachment of structure-related
attributes to occurrences.
Product Structure classes
The PS module works with the following classes of objects:

BOM view

BOM view revision

Occurrence

View type

Note type

Each has associated attributes and methods specific to their class.

BOM view
When an item is an assembly of other items, its assembly structure is represented by
a BOM view. A BOM view is a workspace object. It is an object distinct from the
item in order to support multiple views functionality, when a separate BOM view is
required to represent each different view of an items structure.
The class attributes and methods for BOM view in the PS module are shown in
the following figure:

BOM view class attributes and methods

In the figure:

4-122

Server Customization Programmers Guide

PLM00074 J

ITK customization

Item is the item to which this BOM view belongs, inquired by the
PS_ask_item_of_bom_view function.

BOM view revisions are all of the revisions of this BOM view. They can be listed
using the PS_list_bvrs_of_bom_view function.

Viewtype specifies the type of this BOM view with the tag of a View Type
object. Use the PS_ask/set_bom_view_type functions to inquire or modify
its value, respectively.

BOM view also inherits name and description from the workspace object, which
can be inquired and changed using the appropriate WSOM functions.
A BOM view is created by the PS_create_bom_view function. The name of the
BOM view must be unique for all BOM views of the parent item. Be aware
that no initial revision is created, this is done by a call to the PS_create_bvr
function.
Note

A new or modified BOM view is not saved to the database until you make
a call to the AOM_save function. The item it is placed in is also modified
and must also be saved with a separate call to AOM_save.

BOM view revision

The structure of an assembly item may change between successive revisions of the
item. Therefore the actual structure information of an item revision is stored in a
BOM view revision referenced by that item revision. A revision of BOM view "A"
must specify the structure of a revision of the item that owns BOM view "A".
There is no one-to-one correspondence between item revisions and BOM view
revisions, because where two or more revisions of an item have the same structure
they may share references to the same BOM view revision. A new working item
revision based on a previous released revision retains a reference to the released
revisions BOM view revision until such time as the structure of the working item
revision needs to be modified. An item revision may reference only one revision of
a BOM view at a time.
BOM view revisions are workspace objects. They are presented in the workspace
separately from item revisions for three reasons:

To allow access controls to be placed on the structure of an item revision

independently of access controls on the rest of the item revisions data. For
example, to protect the structure from further modification while detailed
changes are still being made to a drawing.

To allow the structure of an item revision to be put through a release procedure

independently of the rest of the data for an item revision.

To allow for multiple views functionality, when an item revision is able to

reference BOM view revisions of different BOM views, each of which represents
a distinct view of the structure of the item.

By default a BOM view revision is shown in the workspace as a specification of

an item revision.
The class attributes and methods for BOM view revision in the PS module are as
shown in the following figure.

PLM00074 J

Server Customization Programmers Guide

4-123

Chapter 4

ITK customization

BOM view revision class attributes and methods

The occurrences of a BOM view Revision are listed by the
PS_list_occurrences_of_bvr function. A BOM view Revisions
occurrences are either all precise, in which case they reference child item
revisions or they are all Imprecise, in which case they reference child items.
This is determined by the state of the PreciseOrImprecise flag. This flag may
be inquired with the PS_ask_is_bvr_precise function and changed with the
PS_set_bvr_precise/imprecise functions.
Note

The PS_set_bvr_precise function does not set view pseudo folder contents
to ItemRevisions. You need to use the BOM_line_set_precise function
instead. If you have the following code in your ITK program:
PS_set_bvr_precise(bvr);
AOM_save(bvr);

Replace it with the following:

BOM_create_window(&window);
BOM_set_window_config_rule( window, rule);
BOM_set_window_pack_all (window, TRUE);
BOM_set_window_top_line(window, NULLTAG, item_rev, bvrs, &top_line);
BOM_line_set_precise(top_line, TRUE);
BOM_save_window(window);
BOM_close_window(window);

The BOM view of which it is a revision is obtained by calling the

PS_ask_bom_view_of_bvr function.
A new BOM view revision is created using the PS_create_bvr function, giving the
tag of the parent BOM view and the item revision in which it is to be placed.
The PS_revise_bvr function creates a new BOM view revision based on an existing
revision of the same BOM view. The PS_copy_bvr function creates a new BOM
view revision based on an existing revision of a different BOM view.
Note

A new or modified BOM view revision is not saved to the database until you
make a call to the AOM_save function. This also applies when occurrences
of a BOM view revision are modified. Additionally, when a new BOM view
revision is created, the item revision it is placed in is also modified and must
also be saved with a separate call to the AOM_save function.

Occurrences
The single-level structure of an item revision is comprised of a collection of links from
a BOM view revision (the parent) to the items that are components of the assembly
(the children). These links are known as occurrences. An occurrence represents the
usage of an item or an item revision within the product structure of a parent. You
can distinguish between different kinds of occurrences in the product structure by
referring to occurrence types and occurrence sequencing in the Integration Toolkit
Function Reference. (The Integration Toolkit Function Reference is not available in
PDF format. It is available only in the Teamcenter HTML Help Collection.)

4-124

Server Customization Programmers Guide

PLM00074 J

ITK customization

Note

Occurrence is not presented as a distinct class within Teamcenter, rather as

an attribute of BOM view revision. In the PS ITK module, occurrences are
always addressed through their parent BOM view revisions.

Creation, modification or deletion of an occurrence is treated as a modification of

its parent BOM view revision. This allows access control to be centralized on the
BOM view revision. You do not have the danger of two users making simultaneous
changes to different occurrences within the same BOM view revision.
Attaching attribute data
Attribute data can be attached to occurrences. This is data that is specific to a
particular usage of a component item within an assembly, for example usage notes
and find numbers. Data that is generic to all usages of an item should be attributes
of the item itself.
Precise/imprecise
If the child (component part) of an occurrence is a specific item revision, the
occurrence is precise. If the occurrence is a generic reference to an item, it is
imprecise. If you have an imprecise occurrence, the item it references may be
resolved at run time to an exact item revision by the application of a configuration
rule.
Multiple view functionality
To support multiple views functionality, an occurrence also specifies a child BOM
view to allow a particular view of a sub-assembly item to be included in the structure.
Multi-level product structure
A multi-level product structure is built up by BOM view revisions having occurrences
referencing other items with BOM views and so on.
Substitutes
Rather than referencing a single component item, an occurrence can contain links
to several substitute items. Substitutes are interchangeable with one other in the
assembly. However, one of these substitute is specified as the preferred substitute.
All substitute of a single occurrence share the same attributes, the attributes
specified for the preferred substitute.
Any modifications the occurrence substitutes is a modification to the BOM view
revision. Permanent modifications require write access to the BOM view revision.
Temporary modifications may be made during a Teamcenter session but cannot be
saved to the database.
Class attributes and methods
The class attributes and methods for occurrence in the PS module are shown in
the following figure.

PLM00074 J

Server Customization Programmers Guide

4-125

Chapter 4

ITK customization

Occurrence class attributes and methods

Occurrences are not presented as separate objects in the ITK interface. You must
always address an occurrence in the context of its parent BOM view revision using
the tag of the BOM view revision as well as the tag of the occurrence itself. When
you modify an occurrence of a BOM view revision, you modify that BOM view
revision. The change is not written to the database until you save the parent BOM
view revision using the AOM_save function.
Occurrences are created with the PS_create_occurrences function. The
ChildItem is set to the tag of a component item revision or item, depending on
whether the parent BOM view revision is precise or imprecise. The ChildView can
be set to the tag of a BOM view of the ChildItem or to NULLTAG.
You can inquire about the child of an occurrence with the PS_ask_occurrence_child
function or change it with the PS_set_occurrence_child function. When
PS_set_occurrence_child is called, only the child component of the occurrence
is changed. All of the occurrence attributes (find number, notes, and so on) are
retained. This is the functionality employed by the Replace command in the
Structure Manager user interface.
An occurrence may have brief textual notes attached to it. A note is a string of up to
160 characters. Each note has a type defining its purpose (for example, usage, color,
adjustment). An occurrence may have any number of notes, provided each is of a
different type. The type must be one of a set of Note Type objects defined by the
system administrator for a Teamcenter installation. You can access and edit notes
using the PS_list_occurrence_notes, PS_ask/set_occurrence_note_text, and
PS_delete_occurrence_note functions.
A find number is used to identify and sort individual occurrences within a single
level of structure. It is a 15-character alphanumeric string and is inquired or
changed using PS_ask/set_seq_no, respectively.
Occurrence has a quantity attribute containing the amount of the child items
specified by the occurrence (for example, 4 bolts or 1.5 liters of oil). Quantity is stored
as a real number and is accessed by the PS_ask/set_occurrence_qty functions.
A negative quantity means the quantity is undefined.

4-126

Server Customization Programmers Guide

PLM00074 J

ITK customization

Note

An occurrence quantity must be expressed in the unit of measure attached

to the child (component) item referenced by the occurrence. Where a
component item has no unit of measure, the quantity value is interpreted as
the number of component items referenced by the occurrence. An occurrence
which specifies more than one usage of a component item is known as an
aggregate occurrence.
For more information about defining units of measure, see the Integration
Toolkit Function Reference. (The Integration Toolkit Function Reference is
not available in PDF format. It is available only in the Teamcenter HTML
Help Collection).

An occurrence also carries a set of flags for storing additional data. Only one flag
attribute is implemented, PS_qty_as_required. When set, it indicates the child item
is to be used as required. Flags are inquired using the PS_ask_occurrence_flag
function and changed using the PS_set/clear_occurrence_flag functions.
A 4x4 transformation matrix can be stored on an occurrence for passing
positional information to a CAD system and is accessed using the
PS_ask/set_plmxml_transform functions.
By default, the occurrences of a BOM view revision are listed in the
order in which they were created. This order can be altered using the
PS_move_occurrence_to/up/down functions.
Note

A change of ordering is treated as a modification to the parent BOM view

revision. Call the AOM_save function to store the change in the database.
Additionally, this ordering functionality is not available through the
Structure Manager user interface. Occurrences are sorted by find number
unless a different custom sort algorithm is supplied for a Teamcenter
installation.

You can create a substitute with the PS_add_substitute function. It takes an

existing item and makes it a substitute to the existing child of an occurrence. If the
occurrence previously had no substitutes, the existing child is used as the preferred
substitute.
You can delete a nonpreferred substitute with the PS_delete_substitute function.
The preferred substitute cannot be deleted.
You can make a nonpreferred substitute the preferred substitute using the
PS_prefer_substitute function. If the BOM view revision is write-protected or
frozen, the change to the preferred substitute succeeds, but the change cannot be
saved to the database. This case is flagged by the is_temporary return value.
You can find the occurrence substitutes using the PS_ask_has_substitutes and
PS_list_substitutes functions. The PS_ask_has_substitutes function returns
true if the occurrence has two or more substitutes defined. The PS_list_substitutes
function returns a list of the occurrence substitute.
View type
Each BOM view in Teamcenter has a type attribute. A View type is an object
that defines an identifying string for a type of view (for example, design view or
manufacturing). The system administrator defines View types for a Teamcenter
installation.

PLM00074 J

Server Customization Programmers Guide

4-127

Chapter 4

ITK customization

Teamcenter provides a default View type. All BOM views created via the
Teamcenter user interface are of this type. The name of this View type is defined by
the PS_default_view_type_name token in the ps_tokens.h header file .
The class attributes and methods for the View type in the PS module are shown
in the following figure.

View type class attributes and methods

A View type is a site-defined classification of BOM views. You can get a list of all
View types defined for an Teamcenter installation from the PS_view_type_extent
function. You can search for a particular View type by name using the
PS_find_view_type function. You can find the name of a View type object from its
tag by calling the PS_ask_view_type_name function.
Note

Only the system administrator can alter the list of available View types,
using the PS_create_view_type and PS_delete_view_type functions.

Note type
You can attach text notes to occurrences. Each note has a type (for example, usage
or adjustment), which defines the purpose of the note. The possible types of notes
are determined by the set of Note type objects defined for a Teamcenter installation
by the system administrator.
The class attributes and methods for Note Type in the PS module are shown in
the following figure:

Note type class attributes and methods

Note type is a list of types of occurrence note, as defined for a Teamcenter
installation by the system administrator. Each Note type has a short name used as
an identifier (for example, at the head of an attribute column in Structure Manager)
and a description which can be used for a longer explanation of the purpose of the
Note type.
Call the PS_note_type_extent function to get a list of available Note types. To find
individual types by name, use the PS_find_note_type function.
Loading of PS objects
When a call to a PS ITK function needs to access the attributes of an object, that
object (if not already loaded) is loaded automatically. When a call to a PS ITK
function modifies the attributes of an object, that object is locked for modification
automatically if it is not already locked.

4-128

Server Customization Programmers Guide

PLM00074 J

ITK customization

Adding attributes
You can add attributes to PS objects using the PS ITK function. Each class within
the PS module can have a number of client data attributes defined for it. Each
instance of such a class may then have each of these client data attributes set to
reference a POM object. This POM object must be of the class specified in the
definition of the appropriate client data attribute.
Product Structure model
When Teamcenter displays the product structure of an assembly, you see a tree of
item revisions. The following figure shows an example:

Product structure model

This simplistic model is complicated by two additional requirements:
1. Teamcenter does not store references to exact revisions of items. This means the
assembly would have to be modified every time you wanted to use a new revision
of a component. Instead Teamcenter stores a reference to an item and turns this
into an exact item revision at run time by application of a configuration rule.
The PS module itself does not deal with the use of configuration rules (for
detailed information, see Bill of Materials (BOM) module), but configuration
impacts the PS module with the requirement to store references to imprecise
items as well as precise item revisions.
2. PS has been designed to facilitate multiple views functionality. This is done by
using the BOM view object, each of which represents one view of the structure
of the item.
In an imprecise case, a structure references an item as well as a BOM view of that
item. At run time, a configuration rule is applied to find the appropriate revision
of the item. If this component item revision references a revision of the specified
BOM view, then this component is a subassembly whose structure is defined by the
BOM view revision found. Otherwise, this component is treated as a piece part (it is
not further divisible into a substructure). In the precise case, the item revision is
referenced directly by the occurrence, therefore the configuration step is eliminated.
Where used
The PS ITK module supplies three functions to produce where used reports on item
revisions. Each reports parent item revisions having a BOM view revision with
occurrences referencing the given item revision up to a specified number of levels.

PLM00074 J

PS_where_used_all

Server Customization Programmers Guide

4-129

ITK customization

Chapter 4

This function reports all usages regardless of precise/imprecise status and

configuration rules.

PS_where_used_configured
This function applies a configuration rule (from the CFM module) to report
usage in context.

PS_where_used_precise
This function looks at precise occurrences.

Relationship to the BOM ITK module

The BOM ITK module sits at a level above the PS module and beneath the Structure
Manager user interface. It is oriented toward the presentation of and interaction
with product structure and encompasses the application of configuration rules.
The BOM module pulls together information from items, item revisions, BOM view
revisions and occurrences to present them as entries in a bill of materials. The
majority of product structure work can be done using the BOM module with the
exception of creating new BOM views. For this, PS must be called.
The PS ITK module is most useful for lower level operations (such as the large scale
import of structure data into Teamcenter) or batch operations to update specific
structure attributes where the overhead of building up the full presentation of
BOM-related information is not required. Direct calls into the CFM ITK module
can provide configuration information to support use of the PS in this way without
needing to use the BOM module.
Product structure Traversal Engine
The Traversal Engine (TE) is a module that is distributed as a shared library and as
callable subroutines (TE API calls). Typical common tasks include:

Generate reports

Release assemblies

Transfer ownership of Teamcenter objects that constitute the product structure

The Traversal Engine manages the traversal, while you are only required to develop
simple ITK programs. The Traversal Engine allows you to register these functions
at different stages of the traversal. These functions are executed at each node and
contain the information of the nodes, which can be processed. The core module
is programmed in object-oriented programing (OOP), so the framework can be
expanded by adding new classes at a later date, and can also be extended to traverse
any Teamcenter structure such as product structure or folders. Presently the core
module relates to product structure only. The ps_traverse utility, located in the
TC_ROOT/bin directory has also been developed to demonstrate the use of TE.
Basic features
The features of the Traversal Engine are:

4-130

Represents the Teamcenter structure as a tree data structure with each node
representing the Teamcenter object.

Server Customization Programmers Guide

PLM00074 J

ITK customization

Provides user exits at different stages and allows the registration of user-defined
functions known as handlers and selectors.

Allows the handlers and selectors to return statuses that determine the creation
of the tree and the traversal direction.

Allows product structure configuration through revision rules and saved variant
rules during the creation of the tree.

Allows inputs from the command line and configuration file.

Allows you to store and retrieve a float value with a key as a string, typically
used for summing up functionality.

With these features, you can develop programs that:

Generate reports.

Apply task release.

Release assembly, set assembly precise, and other similar tasks

User exits
Teamcenter provides user exits to register selectors and handlers that are executed
at different stages of the traversal activity, such as creation of the tree, traversing in
the forward direction, traversing in the reverse direction, and so on.
Selectors and handlers are user-defined functions that need to be developed following
a template. These functions return the decisions that determine the traversal
direction. These are registered at different stages of the traversal and are executed
during the creation and the traversal of the tree. The selectors are run during the
creation of the tree nodes. These determine the values stored in each node and
decide whether a particular branch needs to be traversed or not. The handlers are
run during the tree traversal. The handlers have the information of the node and
the information pertaining to the Teamcenter object that the node represents.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Minimum requirements
You need the following minimum requirements to run the Traversal Engine:

The Teamcenter ITK development environment.

To develop new programs in TE, knowledge of writing ITK programs is required.

Installation
To confirm that you have installed TE successfully, check if the following have been
added to their respective directories:

PLM00074 J

The libitk.libraryextension library in the TC_ROOT/lib directory.

ps_traverse executable in the $TC_ROOT/bin directory.

Server Customization Programmers Guide

4-131

ITK customization

Chapter 4

The ps_traverse.cfg and te_template_itk_main.c files in the

TC_ROOT/sample/examples directory.

Developing a traversal program

Once you custom develop your selectors and handlers by using the ITK functions
and the TE API calls, you can compile them into an executable by using the compile
and linkitk scripts in the TC_ROOT/sample directory.
API calls are classified into:

Initializing and terminating calls. TE modules have to be initialized to use any

TE call.

Configure PS. These configure the PS using revision rule or saved variant. View
type to traverse also can be specified.

Register handlers and selectors. These register the provided the functions as
selector or handler.

Fill/Traverse. These create the tree and traverse the tree.

User interface calls. These write messages to the log file and console and receive
input from the configuration file and the command line arguments.

Refer to the te.h header file in the TC_ROOT/include/itk directory.

Sample implementation
The te_template_itk_main.c file in the TC_ROOT/sample/examples directory
demonstrates TE functionality. It can be compiled and studied to understand how
new utilities can be developed.

Sharing of data objects

You can use ITK functions to import and export objects as well as use Multi-Site
Collaboration programming techniques.
Object import and export
You use the import/export object functionality to move data that is associated with
Teamcenter objects between Teamcenter sites with either read-only or read/write
privileges.
Note

Use PLM XML import and export when possible.

This functionality is in addition to the IMF_export_file and
IMF_import_file routines which are used to export and import files
between the Teamcenter and the operating system.
The IMF_import_file and IMF_fmsfile_import ITK APIs do not validate
whether the file is a text file or a binary file validation. When using these
APIs, FMS does not attempt to validate the type of file against the type
specified on the function call. The caller must ensure that the file for transfer
is of the specified type.

4-132

Server Customization Programmers Guide

PLM00074 J

ITK customization

Object types
The object types, including all their internal supporting data, that can be
imported/exported between Teamcenter sites are:

Folders
You can choose to export any general folder. You cannot export pseudo folders.
Pseudo folders are folders displayed in your workspace that display objects with
a specialized relationship to an item or item revision.

Datasets
When exporting, you can choose to export either all versions, the latest version,
or a specific version.

Forms
When exporting, you can choose to export a form. The definition of the form
must be identical at both sites.

Item
When exporting, if you choose an item, the item and all its related data (such as
the item revisions, BOM view and BOM view revisions, associated item master
and item revision master forms, and any exportable requirement, specification,
manifestation or reference objects) are exported. Additionally, if the selected
item has an assembly (structure), then all the items that make up the assembly
are exported.
You cannot choose part of an item to be exported. For example, you cannot choose
an item revision alone to be exported. You need to select the item which contains
this item revision, in order to export the item. Similarly, the same would be true
with BOM view and BOM view revision objects.

All Teamcenter files that the dataset represents are exported, including the
operating system files that these encapsulate and the datasets revision anchor.
When you export, there is an option to transfer the ownership to another site. If
the ownership is transferred to a particular site, then when the same objects are
imported at that particular site, they are imported with a read/write privilege. If the
ownership is not transferred, then the ownership of the objects still belongs to the
export site. When these objects are imported at another site, they are imported with
a read-only privilege. Any modifications attempted on them are not be allowed.
Object ownership
If the same owning-user name exists at my importing site as owned it at the
exporting site, then set that user to own it here. Only if that lookup fails does it
resort to the simple rule that the user who runs the import gets to own the object.
When an object is imported, if the user who exported the object exists at the
importing site, the objects owner is switched from the user at the exporting site to
the one at the importing site. If the user does not exist at the importing site, the
owner is the user who performed the import. The group is the group in which the
owner logged into to perform the import.
In general with import, object site ownership takes precedence in determining who
has the right to update the object.

PLM00074 J

Server Customization Programmers Guide

4-133

ITK customization

Chapter 4

Export of released objects

The following rules apply for released objects:

Objects that are within a release process can be exported either with read/write
privileges or with read-only privileges. Access to released objects are governed
by the local rule tree.

If such an object is imported at another site, it cannot be used in a release

process at that site if it was exported with read-only privileges. If it was exported
with read/write privileges, then it can be used in a release process.

If an object is locked (in other words, it has been exported with read-only
privileges and is therefore locked at the receiving site) or it has been exported
with read/write privileges but not re-imported (therefore locked at the sending
site), it cannot be used in a release process.

Note

All released objects are exported with their status (for example, Released
to Manufacture).

Exporting objects the route

The route of exported objects is shown in the following figure.

4-134

Server Customization Programmers Guide

PLM00074 J

ITK customization

Export route
Responsibilities and restrictions when exporting
The following enable you to determine the responsibilities and restrictions when
exporting:

PLM00074 J

It is the responsibility of the user who is exporting objects to inform the system
manager which directories need to be copied and to which site.

It is the responsibility of the system manager to set up the list of other sites
which are known to the local site.

It is the responsibility of the system manager to send directories of the exported

objects to the receiving sites, (for example, using tape, ftp, and so on).

Server Customization Programmers Guide

4-135

ITK customization

Chapter 4

The following significant object types cannot be exported:

Users.

Other system administration objects.

Import semantics
The importing of an object is straightforward unless the same object already exists
at the importing site. In this case, the behavior of the objects is described as follows:

Revisioned objects datasets

Although datasets do not need to have unique names, they do have unique
internal identifiers. Therefore, when a dataset is imported, the system knows
whether it already exists. If the dataset does exist which is the same revision,
no import takes place.

Revisioned objects item

Items need to have unique IDs. When an item is imported, be aware of the
following issues:

It is the responsibility of the user who is exporting objects to inform the

system manager which directories need to be copied and to which site.

If an item with the same ID does not exist in the database, then an item with
that ID is created and owned by the user doing the import.

If an item with the same ID exists in the database, then the requirement,
manifestation, reference and specification objects of the importing item are
added on to the existing item.

Nonrevisioned objects folders

These do not have unique names, therefore there are no problems when
importing objects.

Importing objects the route

The route of imported objects is shown in the following figure.

4-136

Server Customization Programmers Guide

PLM00074 J

ITK customization

Import route
Restrictions when importing
The following restrictions apply when importing an object:

PLM00074 J

An imported object cannot be modified (but may be copied), unless it is exported

with read/write privileges.

When an item is imported read-only, then the following rules apply:

o

Existing requirements and specifications cannot be deleted, and new

requirements and specifications cannot be added.

Existing manifestations and references can be cut, and new manifestations

and references can be added.

Attributes on the imported objects cannot be modified.

Server Customization Programmers Guide

4-137

ITK customization

Chapter 4

The item can be deleted from the database only if the item itself is selected.
You cannot delete any of the item revisions alone.

The BOM view and BOM view revisions cannot be modified.

When an item is imported with read/write privileges (with site ownership), then
the following rules apply:
o

The item cannot be deleted from the database and none of its requirements,
specifications, manifestations and references can be removed. This is
because another site may have a reference to it.

New requirements, specifications, manifestations and references can be

added.

Attributes can be modified.

If the item has been previously imported, the subsequent import does not
delete any references, but may add new ones. This occurs so that the import
does not wipe out any local references you may have added. It is important
to note that references deleted at the originating site are not removed from
the importing site. You may want to delete the item before re-importing it to
ensure that you get an exact copy of the original.

Objects, when imported, are given new ACLs. For instance, the owner (as well as
their group) is updated to that of the importing user. However, if the object was
exported as read-only, the importing user is not able to modify the object.

Object import and export interface

There are three ways to import or export an object:

Using the ITK functions

Using the user interface

Select your objects from the workspace window and pick the appropriate option
(Import or Export) from the Tools menu. Objects are selected as follows:

If you select a (collapsed) folder, all objects inside that folder are exported or
imported that can be exported or imported.

If you select many objects at one time, they can be exported or imported
in a single operation.

There are command line interfaces to execute the export or import process
in batch mode for items only. They are item_export and item_import. For
additional information, see the Utilities Reference.

Note

Imported objects are in the same folder structure as they were when
exported.

PLM XML
You can add user exits to customize filter rules, actions rules, import methods,
export methods, and schema mapping. Develop your code and then use the Business

4-138

Server Customization Programmers Guide

PLM00074 J

ITK customization

Modeler IDE to define the extension and assign it to an extension point. For more
information about working with the Business Modeler IDE and ITK, see the
Business Modeler IDE Guide.
The following table shows the six PLM XML extension points available for
customization in the Business Modeler IDE. Each of these user exits or extension
points has one extension, in other words, the base extension.
Extension
rule

User exit name

Purpose

USER Filter
Registrations

USER_register_plmxml_filters
Allows you to register custom filter rules
used during import/export.

USER
Register
actions

USER_register_plmxml_actions
Allows you to register custom action rules
used during import/export.

USER
Register
Export
Methods

USER_register_plmxml_export_methods
Allows you to register custom export
methods. The export method is registered
for exporting an object out of the
Teamcenter database.

USER
Register
Import
Methods

USER_register_plmxml_import_methods
Allows you to register custom import
methods. The export method is
registered for importing an object into
the Teamcenter database.

USER Schema USER_register_plmxml_schema_mapping

Mapping Regs
Allows you to map Teamcenter and PLM
XML objects.
Using ITK and PLM XML to export a BOM view revision
The following example shows how to use ITK to export a BOM view revision with
PLM XML:
#include <stdlib.h>
#include <tc/tc.h>
#include <tc/emh.h>
#include <tccore/item.h>
#include <itk/mem.h>
#include <pie/pie.h>
#include <bom/bom.h>
#define SampleError 1
#define EXIT_FAILURE 1
#define ERROR_CHECK(x) {
\
int stat;
\
char *err_string;
\
if( (stat = (x)) != ITK_ok)
\
{
\
EMH_get_error_string (NULLTAG, stat, &err_string);
\
printf ("ERROR: %d ERROR MSG: %s.\n", stat, err_string);
\
printf ("FUNCTION: %s\nFILE: %s LINE: %d\n",#x, __FILE__, __LINE__); \
if(err_string) MEM_free(err_string);
\
exit (EXIT_FAILURE);
\
}
\
}
int ITK_user_main(int argc, char* argv[]);
static void initialize ( char *usr , char *upw , char *ugp);
static void display_help_message(void);
static int find_topline_of_itemid(char *itemid,char *rev, int *n_tags, tag_t **tags);
static int export_bvr();
/* Main */
int ITK_user_main(int argc, char* argv[])
{

PLM00074 J

Server Customization Programmers Guide

4-139

Chapter 4

ITK customization

int status = 0;
if ( argc <= 6 )
{
display_help_message();
return( SampleError);
}
char *usr = ITK_ask_cli_argument( "-u=");
char *upw = ITK_ask_cli_argument( "-p=");
char *ugp = ITK_ask_cli_argument( "-g=");
initialize ( usr , upw , ugp );
ITK_set_journalling(TRUE);
export_bvr();
ITK_exit_module(TRUE);
return status;
}
/* Do BVR export */
static int export_bvr()
{
int max_char_size = 80;
char *xmlFileName;
char *logFileName = (char *) MEM_alloc(max_char_size * sizeof(char));
char
*itemid;
char *rev;
int
n_objects = 0;
tag_t *objects = NULL;
// Create PIE session
tag_t session;
ERROR_CHECK( PIE_create_session(&session) );
if ( (xmlFileName = ITK_ask_cli_argument( "-file=" )) == NULL )
{
display_help_message();
return ( SampleError );
}
// Set the name of the XML file to export
ERROR_CHECK( PIE_session_set_file(session, xmlFileName) );
// Set the name of the log file
sprintf(logFileName, "%s.log", xmlFileName);
ERROR_CHECK( PIE_session_set_log_file(session, logFileName) );
// get item id
if ( (itemid = ITK_ask_cli_argument( "-item=" )) == NULL )
{
display_help_message();
return ( SampleError );
}
// Get item revision
if ( (rev = ITK_ask_cli_argument( "-rev=" )) == NULL )
{
display_help_message();
return ( SampleError );
}
// Get tranfermode
int n_transfer_modes;
tag_t *transfer_modes;
ERROR_CHECK( PIE_find_transfer_mode("ConfiguredDataExportDefault", "", &n_transfer_modes,
&transfer_modes) );
if( n_transfer_modes == 0 )
{
printf("Error in finding default transfer mode\n");
return(SampleError);
}
// Set the transfermode on the sessionion
ERROR_CHECK( PIE_session_set_transfer_mode(session, transfer_modes[0]) );
//To export the translations of a localizable properties, call PIE__set_export_languages
// with the language codes that you are interested in to set the locales to PIE Session.
// Get the topline of this item to export
ERROR_CHECK( find_topline_of_itemid(itemid, rev, &n_objects, &objects) ) ;
// Pass in the list of objects and do the export
ERROR_CHECK( PIE_session_export_objects(session, n_objects, objects) );
// Delete the session
ERROR_CHECK( PIE_delete_session(session) );
MEM_free(logFileName);
return( ITK_ok );
}
/* Login */
static void initialize ( char *usr , char *upw , char *ugp)
{
int status = ITK_ok;
char *message;
ITK_initialize_text_services( 0 );
if ( ITK_ask_cli_argument( "-h" ) != 0 )
{
display_help_message();
exit( EXIT_FAILURE );
}
status = ITK_init_module ( usr , upw , ugp );
if (status != ITK_ok)
{
EMH_ask_error_text (status, &message);
printf("Error with ITK_auto_login: \"%d\", \"%s\"\n", status, message);
MEM_free(message);
return ;

4-140

Server Customization Programmers Guide

PLM00074 J

ITK customization

}
else
{
printf ("login to database successful.\n");
}
}
/* Find topline for this item */
static int find_topline_of_itemid(char *itemid,char *rev, int *n_tags, tag_t **tags)
{
tag_t
itemTag = NULLTAG;
tag_t
rev_tag = NULLTAG;
int local_num_tags = 0;
tag_t *local_tags = NULL;
// Find the required item
ERROR_CHECK( ITEM_find_item (itemid, &itemTag) );
if(itemTag == NULLTAG)
{
return(SampleError);
}
//Export only if rev is provided
if (rev != NULL)
{
// Get item revision tag
ERROR_CHECK( ITEM_find_rev(itemid,rev, &rev_tag) );
tag_t
window = NULLTAG;
tag_t
top_line = NULLTAG;
// Create a window for BVR export of this item
ERROR_CHECK( BOM_create_window(&window) );
local_num_tags = 1;
local_tags = (tag_t *) MEM_alloc(sizeof(tag_t) * 1);
local_tags[0] = window;
// Set this item as topline to export
ERROR_CHECK( BOM_set_window_top_line(window,itemTag,rev_tag,NULLTAG,&top_line) );
local_num_tags++;
local_tags = (tag_t *) MEM_realloc (local_tags, sizeof(tag_t) * local_num_tags);
local_tags[local_num_tags-1] = top_line;
}
*n_tags = local_num_tags;
*tags = local_tags;
return ITK_ok;
}
/* Displays help messgage */
static void display_help_message(void)
{
printf( "\n\nsample_plmxml_itk_export:
PLMXML export of a simple BVR" );
printf( "\n\nUSAGE: sample_plmxml_itk_export -u=username -p=password -g=groupname
-item=itemname -rev=itemrevision -file=filename");
printf( "\n
-h
displays this message");
}

Customizing action rules

Actions are a set of methods that can be called before, during, and after the
translation in a PLM XML session. Actions can also limit the translator from doing
things, for example:

Changing the ownership of the data on export.

Modifying the check out status of data on export.

Launching a utility after the import of data.

To register and use a custom action rule for PLM XML export:
1. Register your custom action handler by defining and assigning the USER
Register actions extension in the Business Modeler IDE. For more information,
see the Business Modeler IDE Guide.
2. Once you register the custom action handler through the
PIE_register_user_action function, the name that was used to
register the action handler will appear in the Action Handler list in the PLM
XML/TC XML Export Import Administration application.
Your main goal in writing a action rule is to create a C++ function for that rule. This
function must adhere to the following constraints:

PLM00074 J

Server Customization Programmers Guide

4-141

ITK customization

Chapter 4

The action rule must return ITK_OK = int.

The action must be registered.

Your function must use a parameter that is the tag of the session. The function
signature must adhere to the following:
int your-functionname (METHOD_message_t* msg, va_list args)

Your function must verify that the session tag is valid.

Your function must perform ITK-based calls to the session using the public
interface exposed to the session

Your function can then perform calls to the exposed objects from within the session.
The Teamcenter PLM XML/PIE framework allows for the pre, during, and post
functional processing of action rules on behalf of the user. The typical functional
processing that occurs for each of these types of action rules could be:

Pre-processing
Functions that need to verify or prepare the application, data, or Teamcenter to
prepare for the translation. This rule is executed as follows:
o

For export
Before the translation occurs.

For import
Before the XML document is loaded.

During processing
If the translation engine verifies if you have a during action rule, then it is
executed as follows:
o

For export
After the translation and before saving the XML document.

For import
After the document is loaded and before the translation.

Post-processing
Post-processing is done after the translation is complete, but the session still has
control over the translation.

The following code shows an example of ITK code for a pre-action rule. This example
adds user information to the session prior to translation:
#include
#include
#include
#include
#include
#include
#include
#include

4-142

<itk/mem.h>
<tc/tc.h>
<tc/envelope.h>
<property/prop_errors.h>
<pie/pie.h>
<itk/bmf.h>
<tccore/custom.h>
<user_exits/user_exit_msg.h>

Server Customization Programmers Guide

PLM00074 J

ITK customization

#include <tc/tc_macros.h>
#include <bmf/libuserext_exports.h>
extern USER_EXT_DLL_API int plmxml_user_exit_for_plmxml_actions
(METHOD_message_t* msg, va_list args);
#include <bmf/libuserext_undef.h>
extern int custom_preaction_method(tag_t pie_session_tag)
{
int
ifail
= ITK_ok;
int max_char_size = 80;
char *title = (char *) MEM_alloc(max_char_size * sizeof(char));
char *value = (char *) MEM_alloc(max_char_size * sizeof(char));
printf("Executing custom_preaction_method() ....\n");
strcpy(title, "PLM XML custom pre-action session title");
strcpy(value, "PLM XML custom pre-action session value");
ITKCALL( PIE_session_add_info(pie_session_tag, 1, &title, &value) );
MEM_free(title);
MEM_free(value);
return (ifail);
}
int plmxml_user_exit_for_plmxml_actions(METHOD_message_t* msg, va_list args)
{
int
ifail = ITK_ok;
ifail = PIE_register_user_action( "customPreActionName" ,
(PIE_user_action_func_t)my_custom_preaction_method );
return ( ifail );
}

Customizing filter rules

Filter rules allow a finer level of control over the data that gets translated along with
the primary objects by specifying that a user-written function is called to determine
the operation applied against a given object. For example, you want the following to
occur: if the item revision has a UGMASTER dataset, you want that translated and
all other datasets skipped; if there is no UGMASTER dataset, you want to export
the JT dataset instead. This asks the closure rule to base its traversal on which child
element is in existence, which the closure rule is not designed for. For this kind of
control, you need a filter rule.
To register and use a custom filter rule for PLM XML:
1. Register your custom action handler by defining and assigning the USER Filter
Registrations extension in the Business Modeler IDE. For more information,
see the Business Modeler IDE Guide.
2. Once you register the custom filter through the PIE_register_user_action
function, the name that was used to register the filter rule appears in the Filter
Rule list in the PLM XML/TC XML Export Import Administration application.
The following code shows an example of ITK code for a filter rule. This rule says if
the object in the current call path is not released, do not process the object:
#include <itk/mem.h>
#include <tc/tc.h>
#include <tc/envelope.h>
#include <property/prop_errors.h>
#include <pie/pie.h>
#include <itk/bmf.h>
#include <tccore/custom.h>
#include <user_exits/user_exit_msg.h>
#include <tc/tc_macros.h>
#include <bmf/libuserext_exports.h>
extern USER_EXT_DLL_API int plmxml_user_exit_for_filter_actions

PLM00074 J

Server Customization Programmers Guide

4-143

Chapter 4

ITK customization

(METHOD_message_t* msg, va_list args);

#include <bmf/libuserext_undef.h>
extern int plmxml_user_exit_for_filter_actions(METHOD_message_t* msg, va_list args)
{
int stat
= ITK_ok;
printf("Executing plmxml_user_exit_for_filter_actions() ....\n");
// register custom filter rule here
ITKCALL( PIE_register_user_filter( "customFilterRuleName",
(PIE_user_filter_func_t)custom_filter_rule_method ) );
return stat;
}
extern int custom_filter_rule_method (void *msg)
{
tag_t objTag
= NULLTAG;
WSO_status_t* stats
= NULL;
PIE_rule_type_t result = PIE_travers_no_process;
int cnt
= 0;
int stat
= ITK_ok;
int released = 0;
// Get the object from the call path
ITKCALL( PIE_get_obj_from_callpath(msg, &objTag) );
printf("Object tag = %d \n", objTag);
// Get the oject status
ITKCALL( WSOM_ask_status(objTag, &cnt, &stats));
// usually only one status object returned, ignore others
if ( (cnt >= 1) && (stats != NULL) )
{
POM_compare_dates (stats[0].date_released, NULLDATE, &released);
if( released == TRUE ) // not released yet
{
result = PIE_travers_and_process;
}
}
return result;
}

Setting the target path name

The PIE_session_set_target_pathname function helps to locate a PLM XML file
in a directory other than the working directory. However, the file output does not
recognize nor use this setting. If you are exporting bulk data files and your code
looks like this example where the PIE_session_set_target_pathname function is
called to set the path:
PIE_session_set_transfer_mode(tSession, transfer_mode_tags[0]);
PIE_session_set_revision_rule(tSession,tRevRule);
PIE_session_set_file (tSession, "file-name.xml");
PIE_session_set_target_pathname(tSession,"filepath\\");
PIE_session_export_objects (tSession,1,&children[k]);

Change your code to remove the PIE_session_set_target_pathname function and

add the file path to the file name as shown in this example:
PIE_session_set_transfer_mode(tSession, transfer_mode_tags[0]);
PIE_session_set_revision_rule(tSession,tRevRule);
PIE_session_set_file (tSession, "filepath\\file-name.xml");
PIE_session_export_objects (tSession,1,&children[k]);

If you are not exporting bulk data files, you can use the
PIE_session_set_target_pathname function.

4-144

Server Customization Programmers Guide

PLM00074 J

ITK customization

Data Exchange
Data Exchange allows you to exchange data between Teamcenter and Teamcenter
Enterprise (Teamcenter Enterprise) sites or use Briefcase to exchange data between
manufacturers and suppliers.
Exchanging data between Teamcenter and Teamcenter Enterprise
1. Site 1 requests objects from site 2.
2. Site 2 passes the objects through its scoper, which applies a transfer option set.
The transfer option set contains a transfer mode with closure rules that defines
the data to be passed along with the objects.
3. The site 2 scoper then passes the data to its exporter, which exports the data in
the native XML format of site 2 to the data mapper.
4. The data mapper maps the data to the TC XML format and passes it to the
site 1 importer.
5. The site 1 importer receives the data, passes it through its scoper, and the data
is available for site 1 use.
When you create ITK programs to execute an exchange, you must follow this process
in the code.
There are several include files that contain the functions required for Data Exchange:

tie/tie.h
Contains functions needed for export and import of TC XML files:
TIE_export_objects, TIE_confirm_export, and TIE_import_objects.

pie/pie.h
Contains functions needed for handling transfer option sets:
PIE_get_available_transfer_option_sets and PIE_describe_option_set.

gms/gms.h
Contains functions that ensure that previously replicated data
is synchronized between sites: GMS_synchronize_site and
GMS_identify_outdated_replica_objects.
It also contains functions that import and export objects even if Global
Services is not enabled: GMS_import_objects_from_offline_package and
GMS_export_objects_to_offline_package. These functions can also be used
when Global Services is enabled.

Briefcase
Use Briefcase to exchange data with other Teamcenter sites, either online through a
network connection or offline using an archive file. In addition to the include files
used for Data Exchange between Teamcenter and Teamcenter Enterprise, there are
additional functions required specifically for Briefcase:

PLM00074 J

publication/gms_publication.h

Server Customization Programmers Guide

4-145

ITK customization

Chapter 4

Contains functions required to move objects in and out of the archive file:
GMS_request_remote_export and GMS_request_remote_import.
All export and import calls use Global Services. The
GMS_request_remote_export function requests that the selected object
be exported to a given site. This function is used for both online and offline
exporting. For offline exporting, set the session_option_names parameter to
offline and its corresponding session_option_value parameter to true.

gms/gms_res.h
Contains the functions required to check files in and out: GMS_RES
_site_checkout, GMS_RES _site_checkin, GMS_RES
_cancel_site_checkout, and GMS_RES _is_site_reserved. Use
these functions to lock the object at the remote site that you want to modify and
unlock it when you are done.

TIE framework
A set of wrappers are provided that allow ITK programmers to extend the
Teamcenter Import Export (TIE) framework. Following are the extension tasks
you can perform:

Register the serialize or de-serialize method.

A typical use case for an ITK customization is when an installation has a
user-defined object type extended from an existing POM type. TIE uses the
extension rule functionality in Business Modeler Framework (BMF) to define the
extension rule and handler for a type. ITK programmers can write C functions to
define extension rules and handlers for their own types, and then populate the
database with rules using Business Modeler IDE deploy. Wrappers are provided
for ITK programmers to manipulate XML elements in a PLM XML document,
such as get a PLM XML element by type name, create a PLM XML element by
type name, add an attribute by name, and get an attribute by name.
The message to define serialize method is TIE_serialize. The message to define
the de-serialize method is TIE_deserialize. The input to both serialize and
de-serialize methods is TIE_message_t.

Register schema mapping.

The mapping from Engineering Process Management data to XML elements is
defined by property constants in the database and clauses in the property set.
ITK programmers can use the Business Modeler IDE to add attributes of a
custom class as required attributes in the database or add one clause for each
attribute in the property set. No wrapper is needed.

Manipulate the TIE_message_t structure.

The TIE_message_t structure holds information about the current translation
at any point of time during traversal. A full set of ITK functions is provided for
the ITK programmer to get and set information in the TIE_message_t structure.

Manipulate the GenericSession run-time object.

The GenericSession object holds information given by the end user to perform
a translation. A full set of ITK functions are provided for the ITK programmer to
get and set information in the GenericSession object.

4-146

Server Customization Programmers Guide

PLM00074 J

ITK customization

Register session actions.

The ITK programmer can supply C functions to customize the import and export
process. The following table shows when the action is executed:
Action
pre

Export

Import

Set after the

Set after XSLT is applied, and before
exporter is ready
the PLM XML file is opened for process.
for translation, and
before the translation
starts.

during

Set after objects are

exported, and before
XSLT is applied.

Set after the PLM XML file is opened

for process, and before translation
starts.

post

Set after XSLT is

applied.

Set after objects are imported.

The input to action is the GenericSession object. The wrap is provided for the
ITK programmer to register actions.

Register the ITK filters.

The ITK programmer is able to supply C functions to examine each processed
object based on object type. The input to filter is TIE_message_t.

The following is a list of the ITK functions implemented to register methods:

int TIE_register_user_filter
(char* filterRuleName, TIE_user_filter_func_t user_filter )
int TIE_register_user_action
(char* actionName, TIE_user_action_func_t user_action )

To use these ITK functions, include the tie.h file in C functions.

Multi-Site Collaboration
There are ITK programming techniques and considerations unique to a Multi-Site
Collaboration environment.
Transferring site ownership
If your ITK program transfers Multi-Site site ownership over a network, it must
call the OBJIO_set_site_based_attribute function to use the Synchronous Site
Transfer (SST) protocol.
For more information about this function, see the Integration Toolkit Function
Reference.
Note

PLM00074 J

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Server Customization Programmers Guide

4-147

ITK customization

Chapter 4

Mapping application-specific IDs using Object Directory Services extensions

You can use the Application Reference (APPREF) ITK module to map
application-specific unique IDs to a Teamcenter unique ID. The APPREF functions
populate and query the Publication Record class managed by the Object Directory
Services (ODS) with application-specific data. More than one application-specific
ID can be associated with one Teamcenter item ID. The APPREF functions are
called by the application that needs its IDs mapped to Teamcenter. For example,
Teamcenter Integration for NX I-deas can call APPREF functions to map its GUIDs
to a Teamcenter item ID or UID.
For more information about the APPREF functions, see the Integration Toolkit
Function Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

The functions are called at ODS client sites which are sites that are configured to
communicate with an ODS site using publication and remote search operations.
The TC_appref_registry_site preference defines the ODS site that is used for all
APPREF operations. For more information about this preference, see the Preferences
and Environment Variables Reference.
The following table shows the basic process and data flow for the APPREF module.
Step

ODS client site

ODS site
At startup, the ODS server registers the
APPREF API handler.

Application calls the

APPREF API.

API calls the

distributed ITK
function.

The ODS server calls the registered

APPREF API handler.
APPREF API handler performs the
request and returns the results.

The distributed ITK

function returns the
results to the API.

The API returns

the results to the
application.

Legacy ITK considerations

Before Multi-Site Collaboration, when exporting an object it was possible to omit
the destination or target site, which effectively produced an export file that could be
imported by any site. With the implementation of Multi-Site Collaboration, you are
now required to supply at least one target site.
Although this requirement has been addressed in the interactive Export dialog box
and the item_export utility, it may cause some problems in existing user-written
ITK programs that call OBJIO ITK functions to perform object export.

4-148

Server Customization Programmers Guide

PLM00074 J

ITK customization

However, for those who want to continue using an existing ITK program without any
change, you can do so by performing the following steps:
1. Relink your ITK program with the current libraries.
2. In the Options dialog box, accessed from the Edit menu in My Teamcenter,
define the TC_default_export_sites preference with a list of the desired target
sites. For example:
TC_default_export_sites=
SITE1
SITE2

3. Define the TC_USE_DEFAULT_EXPORT_SITES environment variable and

set it to YES as follows:
export TC_USE_DEFAULT_EXPORT_SITES=YES

Unless this is defined, the preference defined in step 2 is ignored.

4. Run the ITK program.
Caveats
The TC_default_export_sites preference is not used during interactive export
operations.
This procedure is only applicable when not transferring site ownership. If the
ITK program supports transfer of site ownership by calling the OBJIO_set_site
function, this call is re-directed to call the OBJIO_set_owning_site function,
thereby making the ITK program compliant with the Teamcenter requirements.
The OBJIO_set_site function is obsolete. Therefore, Siemens PLM Software
highly recommends that you modify any existing ITK programs to call the
new OBJIO_set_target_sites (when not transferring site ownership) or
OBJIO_set_owning_site (when transferring site ownership) functions.
USER_is_dataset_exportable user exit
The USER_is_dataset_exportable user exit helps refine Multi-Site dataset
exporting. The normal Multi-Site framework allows you only to export all datasets
with a particular relationship, but you cannot further sort out the datasets to export.
For example, assume you have this structure:
Item1
ItemRevision1
Dataset1 (attached to ItemRevision1 with the Reference relation)
Dataset2 (attached to ItemRevision1 with the Reference relation)

If you attempt to export Item1 to a remote site, you can select which relationships
to be exported, and by selecting the Reference relation, you can export both
Dataset1 and Dataset2. However, you cannot export Dataset1 by itself without
also exporting Dataset2.
You can use the USER_is_dataset_exportable user exit to overcome this
limitation. This user exit can be used to check if a dataset should be allowed to be
exported based on its classification type. Following is the code for this user exit:
USER_EXITS_API int USER_is_dataset_exportable
int
n_target_sites,

PLM00074 J

tag_t

dataset_tag,

Server Customization Programmers Guide

4-149

Chapter 4

ITK customization

tag_t *
logical
logical
logical *
)

target_sites,
is_transferring_ownership,
modified_objects_only,
isExportable

Parameter

Input
or
output Description

dataset_tag

Input

Specifies the tag of the dataset object.

n_target_sites

Input

Specifies the number of target sites.

target_sites

Input

Defines the target sites list.

is_transferring_ownership

Input

Indicates if the Multi-Site transfer also

transfers ownership.

modified_objects_only

Input

Indicates if Multi-Site transfer is

transferring only modified objects or
otherwise.

isExportable

Output Indicates if this dataset tag should be

Multi-Site exported or not.

Implement this user exit using standard user exit methods.

For additional information about the ITK USER_is_dataset_exportable user exit,
see the Integration Toolkit Function Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Customizing system administration modules

You can use ITK to customize Teamcenter system administration functionality, such
as creating custom privileges for Access Manager, defining action handlers for Audit
Manager, and create report definitions for Report Builder.
Customize Audit Manager
Perform the following steps to use ITK to define an action handler for Audit Manager:
1. Create a file (for example, my_handler.c) in the \users_exits\code directory
with the following code:
#include <sub_mgr/subscription.h>
#include <user_exits/user_exits.h>
int PEC_Log_Handler(void* message, int nArgs, char** args)
{
TcSubscriptionActionMsg_t* msg =
(TcSubscriptionActionMsg_t*)message;
// add handler code here
return 0;
}

2. Declare the function in the user_exits.h file:

extern USER_EXITS_API int PEC_Log_Handler(void* message, int nArgs,
char** args);

4-150

Server Customization Programmers Guide

PLM00074 J

ITK customization

TcSubscriptionActionMsg_t is defined in the subscription.h file.

3. Compile the file and build the libuser_exits.dll file.
4. Install the handler. For example:
%TC_BIN%\install_handlers -f=create -id=PEC_Log_Handler
-funcname=PEC_log_Handler -functype=1 -execmode=1 exectime=1800

5. Modify the audit definition objects. You can modify the

TC_DATA\auditdefinition.dat file to add the new handler to the
audit definition object you want to change. Then either run the
TC_BIN\define_auditdefs -f=auditdefinition.dat command or interactively
log on to the Audit Manager application in the rich client and modify the audit
definition objects to add the new handler.
Customize Vendor management
Using Teamcenter vendor management, you can model vendor contributions to
a product by capturing information about the vendors and the vendor parts they
provide to satisfy the form, fit, and function of commercial parts.
You can customize your vendor management process with an ITK program. For
example, you may want to write a program that does the following:

Create a commercial part as a component of your product assembly.

Use the VMS_create_commercial_part function.

Create a bid package to provide to vendors so they can develop their quotes.
Use the VMS_create_bidpackage and VMS_create_bidpackage_lineitem
functions. You can also revise your bid package with bid package revisions,
similar to items in Teamcenter.

Create vendors that provide quotes.

Use the VMS_create_vendor function. You can also create vendor roles, such
as distributor or supplier, with the VMS_create_vendor_role function.

Create vendor manufacturer parts and associated quotes that fulfill the
requirements of your commercial parts. The manufacturer part and quote
information is provided by your vendors. You can use different manufacturer
parts for the commercial part in your product.
Use the VMS_create_manufacturer_part function for the
vendor part and connect it to your part information with the
VMS_add_mfg_part_to_comm_part function. Use the VMS_create_quote
function to create the quote and use the VMS_add_quote function to add the
quote information to your bid package line item.
Note

In the user interface, manufacturing parts are called vendor parts.

Include the vm\vms.h file in your program and call the VMS_init_module function
first to initialize the vendor management classes. For an example that uses the
vendor management functions, open the TC_ROOT\sample\vms\vms_util.c file.

PLM00074 J

Server Customization Programmers Guide

4-151

Chapter 4

ITK customization

For more general information about vendor management, see the My Teamcenter
Guide.
For more information about vendor management ITK functions, see the Integration
Toolkit Function Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Customize Volume Management

In Teamcenter, there are two methods to migrate infrequently used data to secondary
and tertiary storage mediums: volume management (VM) and hierarchical storage
management (HSM). Volume management is internal to Teamcenter. Hierarchical
storage management can be used with third-party HSM software tools. In ITK, if you
want to write code for VM or HSM policies, use the functions in the sa/migration.h
include file.
If you want to use a third-party HSM software tool, Teamcenter provides a neutral
API that calls the base method. Use the HSM_migrate_files_msg operation under
the HSM_Policy business object in Business Modeler IDE. For more detailed
information, see the Volume Management Guide. If you want a tight integration with
the third-party tool, you can replace the base method with a customized method.
For more general information about volume management and hierarchical storage
management, see the Volume Management Guide. For more information about the
Volume Management functions, see the Integration Toolkit Function Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Customize Report Builder

When you create report definitions templates, you can write ITK code to create
report definitions and add your own customizations. In addition, there are functions
that retrieve the existing report definitions based on different criteria, such as
report type and source. To create a new report definition template, use the
CRF_create_report_definition function. To retrieve existing report definitions
based on different criteria, use the CRF_get_report_definitions function. To
generate a report based on different input criteria, use the CRF_generate_report
function.
The following example code shows how to create a summary report definition:
static void create_summary_report_defintion()
{
tag_t
rd_tag= NULL_TAG;
tag_t
qs_tag= NULL_TAG;
char *rd_id = "offline_testing_api_ecube_2"; //OLD KEY IS sum_rpt_for_items
char *rd_name = "rd_create_testing";
char *rd_desc = "rd_create_description";
char *rd_source=NULL;
char *queryName="Admin - Employee Information";
tag_t query_t = NULLTAG;
status_t stat = ImanQuery::find(queryName, &query_t);
if ((stat != OK) || (query_t == NULLTAG))
{
printf("ERROR cannot find query %s s \n", queryName);
return;
}

4-152

Server Customization Programmers Guide

PLM00074 J

ITK customization

ITK_CALL( CRF_create_report_definition(rd_id,rd_name,rd_desc,NULL,0,
NULL,0,rd_source,
0,NULL,NULL,//params
query_t, // queru source tag
NULLTAG,
0,
NULLTAG,
&rd_tag) );
printf("New summary report rd Tag: %d\n", rd_tag );
}

The following example code shows how to retrieve item report definitions:
static void list_reports()
{
tag_t *tags = NULL;
int n_tags=0;
const char* itms="itm";
ITK_CALL( CRF_get_report_definitions(itms,NULL,status,NULLTAG,&n_tags, &tags) );
printf("----BEGIN ITEM REPORTS ---n\n");
for (int loopFound = 0; loopFound < n_tags ; loopFound++)
{
String uidString = Tag::tagToUid(tags[loopFound]);
char *seeUid = uidString.smString();
printf(" object tag is: %d object uid = %s\n",tags[loopFound], seeUid);
MEM_free(seeUid);
}
}

The following example code shows how to find and generate a summary report:
static void find_and_generate_summary_report()
{
tag_t
rd_tag= NULL_TAG;
tag_t
qs_tag= NULL_TAG;
const char* id="TC_2007_00_SUM_RPT_0004"; //4 for user stuff
ITK_CALL( CRF_find_report_definition(id,&rd_tag) );
printf("summary report rd Tag: %d\n", rd_tag );
int count=1;
char **entryNames = (char **)MEM_alloc(sizeof(char *) * count);
char **entryValues = (char **)MEM_alloc(sizeof(char *) * count);
int idx = 0;
char *report_path=NULL;
char *param1= "User Id";
char *value1= "*";
entryNames[idx]=param1;
entryValues[idx]=value1;
tag_t dataset = NULLTAG;
char *data_set_name=NULL;
CRF_generate_report(rd_tag,dataset,0, NULL,
count,entryNames,entryValues, ///criteri stuff
data_set_name, /* dataset name */
&report_path );
if ( report_path != NULL )
printf(" Summary report generated at %s",report_path);
}

For more information about Report Builder itself, see the Report Builder Guide. For
more information about the Report Builder functions, see the Integration Toolkit
Function Reference.
Note

PLM00074 J

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Server Customization Programmers Guide

4-153

Chapter 4

ITK customization

Customize subscriptions
You can implement a custom subscription event handler using the
TcSubscriptionActionMsg ITK method. To subscribe using a custom event and
custom handler:
1. Modify the libuser_exits.dll file to include the CUSTOM_event_handler
action handler.
a. Shut down all Teamcenter services.
b.

Rename the TC_BIN\libuser_exits.dll file to libuser_exits.cots.

c.

Copy the TC_ROOT\lib\libuser_exits.ar.lib file to a user_exits directory,

for example, w:\user_exits.

d. Change to the w:\user_exits directory and run the

TC_ROOT\sample\extract_objects.bat sample executable.
e.

Create the custom_subscription_handler.c file.

/*
custom_subscription_handler.c
THIS IS NOT SUPPORTED AS A CUSTOM EXIT (a.k.a. Supplier Custom Hook)
MUST BE ADDED TO libuser_exits shared library
#include
#include
#include
#include
#include

<emh.h>
<tc.h>
<subscription.h>
<user_exits.h>
<stdarg.h>

extern DLLAPI int CUSTOM_event_handler(void* message, int nArgs, char** args)

{
//ImanSubscriptionActionMsg_t* msg = (ImanSubscriptionActionMsg_t*)message;
TcSubscriptionActionMsg_t* msg = (TcSubscriptionActionMsg_t*)message;
/* TC_write_syslog will go to subsucriptionmgr syslog not tcserver syslog */
TC_write_syslog("\n\n\n Running CUSTOM_event_handler \n\n\n");
system("cmd /c \"date /t >> %TC_TMP_DIR%\\_______custom_event.log\"");
return ITK_ok;
}

f.

Save the custom_subscription_handler.c file to the w:\user_exits

directory.

g.

Build the new libuser_exits.dll file.

%TC_ROOT%\sample\compile -DIPLIB=libuser_exits custom_subscription_handler.c
%TC_ROOT%\sample\link_user_exits

h. Copy the libuser_exits.dll to the TC_BIN directory.

i.

Start the Teamcenter services.

j.

Install the handler.

%TC_BIN%\install_handlers -f=create -id=CustomHanderId
-funcname=CUSTOM_event_handler -functype=1 -execmode=1 -retrycount=5
-retryinterval=10 -override=true

2. Create a custom event mapped to a business object type.

a. Create a new event type using the Business Modeler IDE.
For more information, see the Business Modeler IDE Guide.

4-154

Server Customization Programmers Guide

PLM00074 J

ITK customization

Note

b.

The install_event_types utility is deprecated, and therefore you

can no longer create event types using this utility. Instead, you must
create custom event types using the Business Modeler IDE.

Map the event to a business object type using the Business Modeler IDE.
For more information, see the Business Modeler IDE Guide.

c.

Make the event type subscribed.

%TC_BIN%\install_event_types -f=modify -imantype=G9Item -imanclass=G9Item
-eventtype=CustomEventName -subscribe

3. Subscribe to the object and post the event using the ITK utility.
a. Create the subscribe_to_custom_event.cxx file.
/*HEAD SUBSCRIBE_TO_CUSTOM_EVENT.CXX CCC ITK */
/*
%TC_ROOT%\sample\compile -DIPLIB=none subscribe_to_custom_event.cxx
%TC_ROOT%\sample\linkitk -o
subscribe_to_custom_event subscribe_to_custom_event.obj
*/
#ifdef __cplusplus
extern "C" {
#endif
#include <stdlib.h>
#include <stdarg.h>
#include
#include
#include
#include
#include
#include
#include
#include
#include

<emh.h>
<item.h>
<standardtceventtypes.h>
<subscription.h>
<tc.h>
<tcactionhandler.h>
<tceventmgr.h>
<tceventtype.h>
<tctype.h>

static void ECHO(char *format, ...)

{
char msg[1000];
va_list args;
va_start(args, format);
vsprintf(msg, format, args);
va_end(args);
printf(msg);
TC_write_syslog(msg);
}
#define IFERR_ABORT(X) (report_error( __FILE__, __LINE__, #X, X, TRUE))
#define IFERR_REPORT(X) (report_error( __FILE__, __LINE__, #X, X, FALSE))
static int report_error(char *file, int line, char *call, int status,
logical exit_on_error)
{
if (status != ITK_ok)
{
int
n_errors = 0;
const int
*severities = NULL,
*statuses = NULL;
const char
**messages;
EMH_ask_errors(&n_errors, &severities, &statuses, &messages);
if (n_errors > 0)
{
ECHO("\n%s\n", messages[n_errors-1]);
EMH_clear_errors();
}
else
{
char *error_message_string;
EMH_get_error_string (NULLTAG, status, &error_message_string);
ECHO("\n%s\n", error_message_string);
}
ECHO("error %d at line %d in %s\n", status, line, file);
ECHO("%s\n", call);
if (exit_on_error)
{

PLM00074 J

Server Customization Programmers Guide

4-155

Chapter 4

ITK customization

ECHO("%s", "Exiting program!\n");

exit (status);
}
}
return status;
}
static void do_it(void)
{
tag_t event_type = NULLTAG;
IFERR_ABORT(TCEVENTTYPE_find("CustomEventName", &event_type));
if (event_type == NULLTAG)
{
ECHO("CustomEventName not found!\n Exiting Program\n");
return;
}
tag_t handler = NULLTAG;
IFERR_ABORT(TCACTIONHANDLER_find_handler("CustomHanderId", &handler));
if (handler == NULLTAG)
{
ECHO("CustomHanderId not found!\n Exiting Program\n");
return;
}
char *user_name_string = NULL;
tag_t user = NULLTAG;;
IFERR_ABORT(POM_get_user(&user_name_string, &user));
tag_t item = NULLTAG;
tag_t rev = NULLTAG;
IFERR_ABORT(ITEM_create_item("", "Subscribe Test", "G9Item", "", &item,
&rev));
tag_t subscription = NULLTAG;
IFERR_REPORT(SCM_find_subscription( item, user, event_type, handler,
&subscription));
if (subscription != NULLTAG)
{
ECHO("Object Subscription already exists!");
}
else
{
IFERR_REPORT(SCM_subscribe(item, user, event_type, handler, NULLDATE,
NULLDATE, 0, NULL, &subscription));
ECHO("Created new object subscription!\n");
}
int ifail = ITK_ok;
IFERR_REPORT(ifail = TCEVENTMGR_post_event(item, "CustomEventName"));
if (ifail == ITK_ok) ECHO("\n\n\t EVENT POSTED! \n\n");
if (ifail != ITK_ok) ECHO("\n\n\t Something is wrong!! \n\n");
}
int ITK_user_main(int argc, char* argv[])
{
IFERR_REPORT(ITK_initialize_text_services(ITK_BATCH_TEXT_MODE));
IFERR_ABORT(ITK_auto_login());
IFERR_REPORT(ITK_set_journalling(TRUE));
do_it();
IFERR_REPORT(ITK_exit_module(FALSE));
return ITK_ok;
}
#ifdef __cplusplus
}
#endif

b.

Save the subscribe_to_custom_event.cxx file to the w:\ directory.

c.

Build a batch program to subscribe to the object.

%TC_ROOT%\sample\compile -DIPLIB=none subscribe_to_custom_event.cxx
%TC_ROOT%\sample\linkitk -o subscribe_to_custom_event
subscribe_to_custom_event.obj

d. Execute the program.

subscribe_to_custom_event -u=infodba -p=password

e.

4-156

Verify the custom handler executed using one of two methods:

Server Customization Programmers Guide

PLM00074 J

ITK customization

Examine the subscription manager system log for the TC_write_syslog

output.

Check if the TC_TMP_DIR\name_custom_event.log was created.

For general information about subscriptions, see the My Teamcenter Guide.

Workflow
You can customize a procedure using the Enterprise Process Modeling (EPM)
module. The Cascade Release (CR) application is also discussed as an illustration of
a customized procedure. The bulk of the descriptions center on EPM since CR is one
example of how to use EPM. CR provides you with a canned release authorization
mechanism. This section introduces the object model for EPM, state transitions,
and the relationship between the interactive dialog box and the areas that require
programming to meet site-specific requirements.
Enterprise Process Modeling
The EPM module is a tool designed to facilitate the specification of processes
(procedures), resources, and data constrained by a companys business rules. A
typical product information management (PIM) system can be viewed as a process
model consisting of procedures to be performed in a well defined sequence; a resource
model which addresses the users, groups, roles and applications a business uses;
and the data model which addresses the different types of data used to run the
businesss computer-aided applications. The companys business rules determine
how the three models interact with one another. EPM addresses the procedures
portion of this model.
A procedure can be viewed as a task or group of tasks which, when performed in
a certain sequence with defined resources and rules, produces a defined output.
The fundamental element of a procedure is a task. The following figure shows a
model of this.

Task model
EPM is designed to support this model. EPM contains analogs to all the elements of
the task model shown. The relationships are shown in the following table.

PLM00074 J

Task model

EPM

Controls

Business handlers

Server Customization Programmers Guide

4-157

ITK customization

Chapter 4

Task model

EPM

Mechanism

Action handlers

Input/output

Responsible party applications

State

State

A task is always in some state and it can change from one state to another by
successfully performing an action. An action may have pre-conditions and business
rules imposed on it. Any of the imposed business rules must be satisfied before
the proposed action can be performed.
A business rule is a statement of some constraint on the performance of an action.
It may be derived from empirical data and knowledge or other procedures. Tasks
consume resources to produce outputs which, in EPM, are associated to the task by
attachments. Each of the EPM elements is discussed in more detail in the next
section.
EPM object model
EPM is comprised of the following components:

Job

Task

Action

Attachment

Business rule

The following figure is a graphical representation of the EPM object model.

EPM object model

Jobs
A job is the run-time instantiation of a procedure. It is a collection of tasks just as a
procedure is a collection of task definitions. A procedure is the system definition of
a business process. Procedures are defined interactively through the Procedures
dialog box.

4-158

Server Customization Programmers Guide

PLM00074 J

ITK customization

Tasks
A task is a rudimentary element in our process model. Data is associated to it and
some action can be performed on it based upon a specific business rule. It is an
instance of a task definition. Just as task definitions make up a procedure, tasks
make up a job during run time. Subtasks can also make up a task to form an
hierarchy of tasks.
You can use the EPM_ask_sub_tasks function to find the subtasks associated with
a certain task. Similarly, you can use the EPM_ask_sub_task function to find
one subtask attached to a task.
If you want to go up the hierarchy of tasks to find the parent of a given task, use the
EPM_ask_parent function. Use the EPM_ask_root_task function to get to the top
of the task hierarchy. To find out what tasks are assigned to a certain responsible
party, use EPM_ask_assigned_tasks.
The EPM_ask_description function is also available to get a short description of
a task in a character array. If you just want the name of the current task, use the
EPM_ask_name function to get a character array containing the name of the task.
Success and failure paths
You can control condition task branching to follow success or failure paths by setting
the value for the result attribute and then configure paths to accommodate all of
the possible result values. By default, the result attribute is set to either true
or false. However, you can set result to any string value and add as many valid
values as you need. To do this, write and register a custom handler that uses the
EPM_set_task_result function to set the result attribute to a string value. The
code can contain any logic or algorithm you need.
You should configure the process template so there is a one-to-one relationship
between the number of valid result values and the number of paths, unless you
want to overload values onto a single path so the process traverses the same path for
a number of results. For example, if you want five different valid values that can
be used to set result, there must be five separate flow linesone line for each of
the five valid result values. Each line has a value associated with it, and this value
must match one of the potential valid result values. If the value used to set the
result does not match any of the path values, the process does not advance. By
default, the result value is displayed as a label on the flow line associated with a
workflow branch path. You can customized text labels by registering the text string.
Dynamic participants
If you use dynamic participants in your workflow and want to customize the
participants, you can create participants with the EPM_create_participants
function. To add or remove participants for an item revision, use the
ITEM_rev_add_participants or ITEM_rev_remove_participant function,
respectively.
Action handlers
Action handlers are routines that act as the mechanism of the action to which
they are associated. The association between an action and handlers is defined
interactively in the Task Definition dialog box.

PLM00074 J

Server Customization Programmers Guide

4-159

Chapter 4

ITK customization

Actions can be either displayed during run time or triggered programmatically. To

display the action string of the current action applied to a task during run time, use
the EPM_task_action_string function. To trigger actions programmatically, use
the EPM_trigger_action function to trigger an action in a specific task. This is
useful in triggering a parallel task to start.
After writing your own handlers, you need to register them to the system using the
EPM_register_action_handler function. This makes the handler available for
use by the system administrator in implementing EPM procedures. The system
administrator can enable the system to find your custom handler and execute it
whenever the action with which the handler was associated is invoked on a task.
For instructions about how to register handlers, see the Business Modeler IDE Guide.
Predefined actions
EPM comes with predefined actions that can occur on any task.
Predefined action

Definition

Assign

Assigns a user or group to perform the work.

Start

Starts a task if it has not been started.

Complete

Marks a task as being completed.

Skip

For a given job, skips this subtask, but marks it complete

for all other tasks that depend on it being completed before
they can start.

Suspend

Suspends all work on this task until further notice.

Resume

Resumes the task to the state it was in before it was

suspended.

Perform

Executes user-defined action handlers any time the user

wants. The Perform task action is executed based on a list
of actions that occur at various times throughout the task.
It does not necessarily execute after the Start task action
but before the Complete task action.
For example, the Add Attachment action
(EPM_add_attachment_action) executes a
handler placed on the Perform task action of the root task
three times before executing a handler placed on the Start
task action.
The following are the available Perform actions:

4-160

Server Customization Programmers Guide

Add Attachment

Remove Attachment

Approve

Reject

Promote

PLM00074 J

ITK customization

Predefined action

Note

Definition

Demote

Refuse

Assign Approver

Notify

These do not change the state of the task.

State transitions
Some actions cause state transitions. For example, applying the Assign action to
a task that is in the Unassigned state causes a state transition to the Pending
state. Applying the Start action causes a state transition from Pending to Started.
Applying the Complete action can cause a state transition from Started to
Completed.
As the action handlers are executed, the task keeps track of its progress by setting
an attribute called state. You can inquire about the state of a task using the
EPM_ask_state function. Next use EPM_ask_state_string to get the string value
of the state. Possible states that a task can take are as follows:

Unassigned

Pending

Started

Completed

Skipped

Suspended

State transition example

As an example of using state transitions, assume that our task is to do circuit
analysis on a circuit design. During the circuit analysis procedure definition the
rule and action handlers are associated with the Start action, the Perform action,
and the Complete action of our task.
The Start action has rule handlers to check that all the files required for analysis
are present. The rule handlers associated with the Complete action check to
make sure the Perform action is invoked. The Perform action is where the actual
analysis program is called by an associated action handler.
The initial state of the task is Unassigned. To start the task, initiate a job in the
workspace using the circuit analysis procedure. The Assign action of the task
is invoked automatically. If the assignment action is successful, the task state
transitions from Unassigned to Pending and the Start action is invoked. The
business rule handlers associated with the Start action are then executed.

PLM00074 J

Server Customization Programmers Guide

4-161

Chapter 4

ITK customization

Assuming that the files required for analysis are all present, there is rule compliance
with the Start action; therefore the task state transitions from Pending to Started.
EPM invokes the Complete action automatically. Since the Perform action has
not been invoked, there is no rule compliance in the Complete action; hence state
transition from Started to Complete does not occur.
Next, invoke the Perform action and do the actual circuit analysis. Assuming the
circuit analysis is successful, invoke the Complete action manually to finish the
job. At this point there should be rule compliance to the Complete action business
handler since the Perform action was done successfully prior to invoking the
Complete action. The task state then transitions from Started to Completed.
Attachments
Attachments are other objects that are associated with the task during run time.
These objects are typically items that need approval, supporting data, forms that
need to be completed for the task, and so on. There are several built-in types of
attachments.
For a complete list, see the Enterprise Process Modeling section of the Integration
Toolkit Function Reference. (The Integration Toolkit Function Reference is not
available in PDF format. It is available only in the Teamcenter HTML Help
Collection.)
Note

If you want task comments to display in the thin client user interface, you
must use customize your workflow using ITK.

Use the EPM_ask_all_attachments function to get an array of all attachments

regardless of task type. To get attachments of a certain type, use the
EPM_ask_attachments function, passing one of the valid attachment types as
an argument. To add an attachment to a task, use the EPM_add_attachments
function. You can remove an attachment with the EPM_remove_attachments
function.
You can also define your own attachment types. This can be done by following a
similar procedure for adding new actions. Modify the tc_text_locale.xml file to
define the EPM_attachment_number display name. The value of number must be
in the range of 1000 to 32000 (1000 < number < 32000). For example:
<key id=EPM_attachment_1001>ECN</key>

For ease of maintenance, define the ECN macro in your local header file. For
example:
#define ECN (EPM_user_attachment +1)

Business rule handlers

Business rule handlers are programs that check compliance to business rules
before any action handlers can be executed within an action. Like action handlers,
the association between action and rule handlers is defined interactively in
the Task Definition dialog box. There are business rule handlers available
in the system that you can readily use or you can write your own. Use the
EPM_register_rule_handler function to register the rule handlers you have
written.

4-162

Server Customization Programmers Guide

PLM00074 J

ITK customization

Customizing a procedure with EPM

A procedure can be customized with EPM in several ways. The simplest method is
to associate available action or rule handlers from the toolkit to specific actions to
obtain the desired result. With this method, you do not need to write a program
or function to customize a procedure. If none of the available handlers meet your
specific needs, then you can write a custom handler using the ITK. Such a custom
handler can then be used along with the Teamcenter-provided handlers to specialize
the behavior of a task.
A handler is a small ITK function designed to accomplish a specific job. There are
two kinds of handlers: rule handlers and action handlers. Rule handlers enforce
business rules. An action handler causes something to happen and usually is
responsible for a state transition.
If the rule handler returns an EPM_go, then the action handlers are executed and a
state transition occurs. If the rule does not return EPM_go, then the action handler
does not execute and the state transition does not occur.
Writing your own action handler
Since action handler programs are essentially ITK functions, they should be written
based on the same guidelines followed in ITK programs. The epm.h header file
must be included in your source code. The standard interface for an action handler
is as follows:
int sample_handler(EPM_action_message_t message)

The EPM_action_message_t is a typedef defined as:

typedef struct EPM_action_message_s
{
tag_t task;
EPM_action_t action;
EPM_state_t proposed_state;
TC_argument_list_t* arguments;
tag_t data;
} EPM_action_message_t;

The fields for EPM_action_message_s are as follows:

task
Task on which the action was triggered.

data
System data.

action
Action that was triggered.

proposed_state
State that the task changes to after actions are completed without errors.

arguments
Argument specified in the procedure.

PLM00074 J

Server Customization Programmers Guide

4-163

Chapter 4

ITK customization

Note

The action handler must return an int status code that can be compared to
ITK_ok to determine if the handler was executed successfully.

Create your own action handler

1. Write the action handler program following the standard interface and the ITK
programming standards.
2. Compile your program using the compile script in the TC_ROOT/sample
directory. The sample compile script writes the resulting object file in the current
directory. Modify the compile script if the default behavior is not sufficient.
3. Register your new handler to the system by writing a module
initialization function (or modifying it if one already exists) to call the
EPM_register_action_handler function for the action handler you have
written. Compile the module initialization function.
Note

Complete step 4 only if this is the first handler you are registering. You
can skip this step for the subsequent handlers that you are going to write.
You can also register handlers using the Business Modeler IDE.
For instructions, see the Business Modeler IDE Guide.

4. Modify the user_gsshell.c file in the TC_ROOT/sample directory to add a call

to your module initialization function in the USER_gs_shell_init_module
function. Compile the user_gsshell.c file using the TC_ROOT/sample/compile
script.
5. Create the user exits library with the TC_ROOT/sample/link_user_exits
script. This script creates the libuser_exits sharable library from all of the
object files in your current directory.
Action handler example
The following is an example of an action handler:
int EPM_system(EPM_action_message_t msg)
{
int err = ITK_ok;
char* arg = 0;
if(TC_number_of_arguments(msg.arguments)>0)
{/* get first argument */
arg = TC_next_argument(msg.arguments);
system(arg);
}
return err; /*return an ITK error code if an error/
occurred*/
}

The first call to the TC_next_argument function gets the first argument, given the
Arguments field from the structure, specified in the task definition windows for this
handler. Each successive call to TC_next_argument gets the next argument on the
list. Use the TC_init_argument_list function to start over at the beginning of the
list and get the first argument. All action handlers should return either ITK_ok if
no error occurred or the ITK error for the error that did occur.

4-164

Server Customization Programmers Guide

PLM00074 J

ITK customization

Writing your own rule handler

The standard interface for a business rule handler is:
EPM_decision_t sample_rule_handler/
(EPM_rule_message_t message)

EPM_decision_t
The EPM_decision_t is a user-defined type defined as:
typedef enum EPM_decision_e
{
EPM_nogo,
EPM_undecided,
EPM_go
} EPM_decision_t;

The fields for EPM_decision_t are as follows:

EPM_nogo
Constraints for rule or rule handler are not satisfied; action and state transition
should not occur

EPM_undecided
Still unknown whether the decision is a go or no go because of insufficient or
pending data; action and state transitions should not occur

EPM_go
Rule or handler passed; constraints satisfied

EPM_rule_message_t
The EPM_rule_message_t is a typedef defined as:
typedef struct EPM_rule_message_s
{
tag_t task;
EPM_action_t proposed_action;
TC_argument_list_t* arguments;
tag_t tag;
} EPM_rule_message_t;

The fields for EPM_rule_message_t are as follows:

task
Task on which the action was triggered

proposed_action
Action that was triggered

arguments
Argument specified in the procedure

tag
System data

PLM00074 J

Server Customization Programmers Guide

4-165

Chapter 4

ITK customization

Create your own rule handler

1. Write the rule handler program following the standard interface and the ITK
programming standards.
2. Compile your program using the compile script in the TC_ROOT/sample
directory. The sample compile script writes the resulting object file in the current
directory. Modify the compile script if the default behavior is not sufficient.
3. Register your new handler to the system by writing a module
initialization function (or modifying it if one already exists) to call the
EPM_register_action_handler function for the rule handler you have written.
Compile the module initialization function.
Note

Complete step 4 only if this is the first handler you are registering. You
can skip this step for the subsequent handlers that you are going to write.

4. Modify the user_gsshell.c file in the TC_ROOT/sample directory to add a call

to your module initialization function in the USER_gs_shell_init_module
function. Compile the user_gsshell.c file using the TC_ROOT/sample/compile
script.
5. Create the user exits library with the TC_ROOT/sample/link_user_exits
script. This script creates the libuser_exits sharable library from all of the
object files in your current directory.
Rule handler example
The following is an example of a rule handler:
EPM_decision_t
EPM_check_responsible_party(EPM_rule_message_t msg)
{
int s;
EPM_decision_t decision = EPM_nogo;
char * userName;
tag_t aUserTag, responsibleParty;
s=EPM_ask_responsible_party(msg.task, &responsibleParty);
if (responsibleParty == NULLTAG)
{
decision = EPM_go;
}
if (s == ITK_ok && decision == EPM_nogo)
{
s = POM_get_user (&userName, &aUserTag);
MEM_free (userName);
if (s == ITK_ok)
{
if (aUserTag == responsibleParty)
decision = EPM_go;
}
}
return decision
}

Registering rule handlers

All rule handlers must be registered. The following example illustrates how you
register a rule handler.

4-166

Server Customization Programmers Guide

PLM00074 J

ITK customization

Note

You can also register handlers using the Business Modeler IDE.
For instructions, see the Business Modeler IDE Guide.

The following example uses the USER_epm_init_module function that

registers a function called EPM_check_responsible_party through the
EPM_register_rule_handler function as the EPM-check-responsible-party
handler.
When defining tasks interactively, use the registered name of the
EPM-check-responsible-party handler to add the handler to an action instead of
the full name of the function, EPM_check_responsible_party:
int USER_epm_init_module()
{
int s;
s = EPM_register_rule_handler("EPM-check-responsible-party", "",
EPM_check_responsible_party);
return s;
}
Register the USER_epm_init_module() function through USER_gs_shell_init_module().
The USER_gs_shell_init_module() function exists in user_gsshell.c located in the
user_exits directory. The registration is shown as follows:
USER_gs_shell_init_module()
{
...
USER_epm_init_module();
}

Compile all of the above mentioned code and create a user exits library. For more
information about creating a user exits library, see the Integration Toolkit Function
Reference.
Note

The Integration Toolkit Function Reference is not available in PDF format. It

is available only in the Teamcenter HTML Help Collection.

Using validation rules

A validation rule is an instance of a Validation Data object with the following
additional run-time attributes:

PLM00074 J

A validation agent that can be an NX CheckMate checker.

The dataset types where the validation agent is applicable.

Whether the check is mandatory or optional. A mandatory check must both run
and pass. An optional check must run but does not have to pass.

Event names where the check is applicable. When applicable event names are
specified for a validation agent (checker), the check result is verified only when
these events happen. If no event name is specified, the checker applies to all
events. The event name can contain an asterisk as a wildcard. Event names
can be marked as exclusive.

A list of parameter and value pairs. The parameter values need to be verified
from the validation result log file.

Server Customization Programmers Guide

4-167

ITK customization

Chapter 4

Validation rules are defined based on your business model. In a production

environment, you can define multiple validation rule files to suit different business
processes.
Validation rule file
Validation rules can be defined in an XML file called a validation rule file. A
validation rule file defines all validation rules for a validation rule set. Follow these
guidelines when you create a validation rule file:

The Rule_Set tag attributes name, description, user, and date are
mandatory. These attributes are mapped as Teamcenter validation rule set
object attributes when the XML rule set is imported.

The Rule tag defines a rule.

o

Checker tag
This tag is mandatory. Its name attribute is the checker class name, not
the display name.

Mandated tag
This tag is mandatory. If a check is mandatory (the check must run and
pass), type yes between the opening and closing tag. If not, type no. When a
check is not mandatory, the check must run, but the result status is ignored.

Datasets tag
This tag is mandatory. You must define the list of applicable dataset types.

Events tag
This tag is optional. The events contain the event values where the check is
applicable. If you do not define an event value list, then the rule applies at
all times. The event values can contain an asterisk as a wildcard. The values
listed can be exclusive when the exclude attribute is set to yes.
If you define the class attribute for the Events tag, you set which target
revision attribute value should be tested against event values list.

Parameter tag
Only parameters that logged in profile level (for a profile check result log file)
are supported. Child checker parameters must be promoted into the profile
level to be verified by the validation rule APIs.

You can define rules in any order in the validation rule file.

The same checker can be instanced in the definition of more than one rule
in the same rule file.

The following sample shows an example of a validation rule file:

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="validation_rule.xsl"?>
<Rule_Set
name="Test_rule_set_1"

4-168

Server Customization Programmers Guide

PLM00074 J

ITK customization

description="Power Train Event 0 at Milestone 3"

user="your_user_id" date="2005-12-25"
xmlns="http://www.plmxml.org/Schemas/PLMXMLSchemaValidationRule"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.plmxml.org/Schemas/
PLMXMLSchemaValidationRule validation_rule.xsd"
>
<Rule>
<Checker name="mqc_check_dim_attach_solid"></Checker>
<Mandated>no</Mandated>
<Datasets>
<type>UGMASTER</type>
<type>UGPART</type>
</Datasets>
<Events class="ITEMREVISION:owning_group" exclude="yes">
<value>chassis.pe.company</value>
<value>powertrain.pe.company</value>
</Events>
</Rule>
<Rule>
<Checker name="mqc_examine_geometry"></Checker>
<Mandated>yes</Mandated>
<Datasets>
<type>UGPART</type>
<type>UGMASTER</type>
</Datasets>
</Rule>
<Rule>
<Checker name="mqc_check_dim_attach_solid"></Checker>
<Mandated>no</Mandated>
<Datasets>
<type>UGPART</type>
</Datasets>
</Rule>
<Rule>
<Checker name="mqc_exam_geom_combo"></Checker>
<Mandated>no</Mandated>
<Datasets>
<type>UGMASTER</type>
<type>UGPART</type>
<type>UGALTREP</type>
</Datasets>
<Events exclude="no">
<value>Status*3</value>
<value>Status_4</value>
</Events>
<Parameters>
<Parameter operation="=" title="Check Tiny objects"
value="TRUE></Parameter>
<Parameter operation="=" title="Check Misaligned Objects"
value="TRUE"></Parameter>
</Parameters>
</Rule>
<Rule>
<Checker name="mqc_examine_geometry"></Checker>
<Mandated>no</Mandated>
<Datasets>
<type>UGMASTER</type>

PLM00074 J

Server Customization Programmers Guide

4-169

Chapter 4

ITK customization

<type>UGPART</type>
</Datasets>
<Events exclude="no">
<value>S*</value>
</Events>
<Parameters>
<Parameter operation="=" title="Save Log in Part"
value="TRUE></Parameter>
</Parameters>
</Rule>
</Rule_Set>

Validation rule APIs

The following sample shows how to call validation rule APIs to perform a validation
result check with the validation rules:
validation_rule_t *validation_rules = NULL;
int
num_rule = 0;
candidate_validation_result_t *candidates = NULL;
int
num_candidates = 0;
/**********************************************
* Get Validation Rule list
**********************************************/
ifail =
VALIDATIONRULE_get_rules (
rule_item_revision,
NULL,
current_event,
&validation_rules,
&num_rule
);
/**********************************************
* Before calling VALIDATIONRULE_get_candidate_results() to get candidate
* result list, user may want to put codes here to resolve all unresolved
* rules.
**********************************************/
ifail =
VALIDATIONRULE_get_candidate_results(
target_objects,
count,
validation_rules,
num_rule,
&candidates,
&num_candidates
);
/**********************************************
* check validation result for each candidate
*/
for( int inx=0; inx<num_candidates; inx++)
{
ifail = VALIDATIONRULE_verify_result(
&(candidates[inx])
);
}
// Before exit, free up allocated memories
VALIDATIONRULE_free_rules(validation_rules, num_rule);
VALIDATIONRULE_free_results(candidates,num_candidates);

4-170

Server Customization Programmers Guide

PLM00074 J

ITK customization

EPM hints
Helpful hints for working with EPM include how to use action handlers in the EPM
process.
Perform action handlers
The rule and action handlers associated with the Perform action get called every
time an action with an action code greater than or equal to EPM_perform_action
is triggered. Clicking the Perform button calls the EPM_trigger_action function
with the action equal to EPM_perform_action.
Many existing ITK functions also call the EPM_trigger_action function to allow
you to customize Teamcenter. The following table lists actions that are triggered
inside each ITK function.
ITK function

Action code

EPM_add_attachment

EPM_add_attachment_action

EPM_remove_attachment

EPM_remove_attachment_action

CR_set_decision

EPM_approve_action

CR_set_decision

EPM_reject_action

CR_promote_target_objects

EPM_promote_action

CR_demote_target_objects

EPM_demote_action

Branching in your handler

You can branch logically in your handler by using message.action in an if/else
block. For example:
if (message.action == EPM_add_attachment_action)
{
/* do something */
}
else
{
/* do nothing */
}

Avoiding infinite loops in perform actions

Infinite loops can occur when performing actions if logic is not included to test the
values of the actions being triggered. For example, the following action handler,
my_action_handler, is executed when a Perform action is triggered:
int my_action_handler(EPM_action_message_t msg)
{
.........
.........
err = EPM_add_attachment (.................................);
.........
.........
return err;
}

When the err = EPM_add_attachment (..........) statement is executed,

my_action_handler is called again as a part of the EPM_add_attachment

PLM00074 J

Server Customization Programmers Guide

4-171

Chapter 4

ITK customization

call. This is because EPM_add_attachment calls EPM_trigger_action with

an action code of EPM_add_attachment_action. Since all action codes greater
than EPM_perform_action get sent to all of the perform action handlers, this
causes an infinite loop.
To avoid this scenario, you should check the action being triggered inside each
handler. To avoid entering an endless loop in the example shown above, add the
following lines to your code:
if(msg.action > EPM_perform_action)
return ITK_ok;

For example:
int my_action_handler(EPM_action_message_t msg)
{
if(msg.action > EPM_perform_action)
return ITK_ok;
......... /* initial lines of code for action */
......... /* handler initiation */
err = EPM_add_attachment (.................................);
......... /* final lines */
......... /* of code */
return err;
}

4-172

Server Customization Programmers Guide

PLM00074 J

Appendix

PLM00074 J

Glossary

Server Customization Programmers Guide

Appendix

Glossary

A
access control list (ACL)
Access Manager component that contains a list of accessors and, for each accessor,
the privileges granted, denied, and not set.
Access Manager (AM)
Teamcenter application that enables the system administrator to grant users access
to Teamcenter objects.
ACL
See access control list (ACL).
action handler
Handler used to extend and customize workflow task actions. Action handlers
perform such actions as displaying information, retrieving the results of previous
tasks (inherit), notifying users, setting object protections, and launching applications.
See also task handler.
action rule
Business rule that defines the actions required in different time phases (precondition,
preaction, and postaction) for create, save as, and delete operations. Action rules are
applied to items, item revisions, and datasets.
aggregate occurrence
Single occurrence using the quantity attribute to represent multiple uses of the same
component item. An aggregate occurrence is used where separate occurrences are
not required to distinguish individual uses (for example, transforms in NX). Rivets
are typically shown as an aggregate occurrence.
allocation
Relationship between constituents of two structural views of a product, for example,
a relationship between constituents of the functional breakdown and the physical
breakdown of a product.
AM
See Access Manager (AM).
architecture
Set of decisions, patterns, and principles for a product suite. The architecture
provides a framework for application development within that product suite and is
independent of specific functions.

PLM00074 J

Server Customization Programmers Guide

A-1

Glossary

Appendix A

assembly
Compound object that is assembled from other objects and may add additional
information to their interpretation.

In the context of an assembly, other assemblies are called subassemblies, while

noncompound objects are called components.

A single-level compound object that is distinct from a multilevel product

structure or bill of materials, which is a hierarchy of assemblies. Assembly
data is stored in a BOM view revision.

attribute
Named storage variable that describes an object and is stored with the object. Users
can search the database for objects using object attributes.
In an object, an attribute is a name/value pair; in the database, an attribute is a field.
attribute inheritance
Process by which a new class automatically inherits all the attributes defined for
all its ancestor classes.
audit definition
Object that creates audit logs to track selected properties for specified actions in
the database. These properties can include custom properties added by a system
administrator.
Audit Manager
Teamcenter application that enables a system administrator to create audit
definition objects, enable/disable audit trail logging, and control audit log access.
Audit definition objects create audit logs that users can view from Teamcenter
applications. Users can audit any Teamcenter object and event type with an audit
definition.
B
BLOB
Binary large object; attribute type of undefined structure. BLOBs are stored as
binary images within an object.
BOM
Bill of materials.

100% BOM
The as sold product configuration, for example, the configuration of a car to be
built and shipped to the dealer.

120% BOM
Partial overlay of selected variant conditions. You cannot build the product
from a 120% BOM.

150% BOM
Overlays of all possible variant configurations. You cannot build the product
from a 150% BOM.

See also design bill of materials and manufacturing bill of materials.

A-2

Server Customization Programmers Guide

PLM00074 J

Glossary

BOM view
Teamcenter object used to manage product structure information for an item.
BOM view revision (BVR)
Workspace object that stores the single-level assembly structure of an item revision.
Access can be controlled on the structure (BOM view revision) independently of
other data. BOM view revisions are meaningful only in the context of the item
revisions for which they are created.
Business Modeler IDE
Teamcenter application that enables a customer to define data model objects such as
business objects, classes, attributes, lists of values, and rules.
BVR
See BOM view revision (BVR).
C
class
Set of objects that share the same list of attributes but distinguishable by the value
the attributes acquire for specific objects. For example, the Automobile class can be
defined by the brand, color, and price, but each car associated to the Automobile
class has a different brand, color, and price combination.
class hierarchy
Structure defining subclasses that inherit the attributes of their superclasses, also
called their parents or ancestors.
client
Role played by a software component of a system when it requests particular services
be performed on its behalf by another entity, a server. See also server.
client tier
Teamcenter architectural tier that comprises the Teamcenter clients, Teamcenter
integrations with third-party applications, and the third-party applications
associated with the integrations.
closure rule
Definition or rule that allows the Teamcenter traversal algorithm to identify the
additional objects required for a specific principal object.
component

Objects used to build up an assembly or subassembly.

Part in a product structure defined in Teamcenter. A component is the lowest

level part in the product structure: it cannot be broken down into subparts.

compound property rule

Business rule that defines run-time properties on an object that references and
relates to a property on a source object. Compound property rules relate to the
property associated with type components. Applied types are item, item revision,
dataset, and form.

PLM00074 J

Server Customization Programmers Guide

A-3

Glossary

Appendix A

configuration rule
Rule that configures a structure. There are two kinds of configuration rules: revision
rule and variant rule.
connection
Object that defines the connectivity between two or more terminals in a physical
model.
corporate server
Host computer at the center of a Teamcenter network. This host contains the
Teamcenter application root directory, Teamcenter data directory, licensing, File
Management System (FMS), and volumes. For installations that include the Web
tier (four-tier architecture), the corporate server also contains the Teamcenter server
manager. Multiple application clients can map to or mount the corporate server.
D
Data Integration Services Adapter
Teamcenter software component that integrates Teamcenter lifecycle visualization
with both the thin client and the rich client.
dataset
Teamcenter workspace object used to manage data files created by other software
applications. Each dataset can manage multiple operating system files, and each
dataset references a dataset tool object and a dataset business object.
dataset business object
Teamcenter object that contains a list of tools that can operate on a dataset.
dataset tool
Teamcenter object that is the tool used to create or modify a dataset.
derived default
Default value that depends on a condition (for example, radio = stereo IF car type =
GLX). Compare with fixed default.
design bill of materials
List of components and subassemblies used to define an assembly structure, and
the representation of the assembly structure. Compare with manufacturing bill
of materials.
direct model dataset
Dataset containing a JT (visualization) file.
E
effectivity
Identification of the valid use of an aspect of product data tracked by unit, date, or
intent. You can specify a start definition, end definition, or both for a particular
effectivity. There are three types of effectivities:

A-4

Unit effectivity specifies the range of item units or serial numbers.

Date effectivity specifies the range of dates. This is also known as an

incorporation point.

Server Customization Programmers Guide

PLM00074 J

Glossary

Intent effectivity specifies a purpose, target, or milestone, for example,

Production, Prototype, or Carryover.

effectivity rule
Rule used to set effective dates on released products and processes with a released
status.
Embedded Software Solutions
Optional extension to Structure Manager and My Teamcenter that allows you to
manage embedded software binaries as part of the product structure.
enterprise process modeling
Modeling used to accomplish workflow objectives. Enterprise process modeling
models workflow processes, allocates resources, and manages data according to
business rules.
enterprise tier
Teamcenter architectural tier that comprises a configurable pool of Teamcenter
C++ server processes and a server manager. Larger sites can distribute the pool of
server processes across multiple hosts. Smaller sites can run the pool of servers on
the same host as the Web tier.
envelope
Teamcenter workspace object that represents a mail message sent by a Teamcenter
user. Envelopes can be used to send workspace object references as well as text
messages.
equipment
Description of the equipment used to perform manufacturing operations.
extension
Method or listener implemented for an extension point.
extension point
Event or capability in the system, such as a precondition, preaction, or postaction,
that allow you to implement custom behavior.
extension rule
Business rule that adds predefined behavior to a business objects operation and fires
as a precondition, preaction, or postaction.
external extension
Extension created by a user to implement customized behavior.
F
feature
Physical or geometric object associated with a product, component, or part.
Alternatively, a logical attribute of a product, component, or part. Examples: a weld
point, a signal, or a geometric pattern. A feature may be represented by a generic
design element (GDE) in a BOM. See also generic design element.
File Management System (FMS)
System that manages uploading and downloading file data between clients and
volumes in both two-tier and four-tier architecture deployments.

PLM00074 J

Server Customization Programmers Guide

A-5

Glossary

Appendix A

FMS provides volume servers for file management, a shared server-level

performance cache for shared data access between multiple users, a client-based
private user cache for rich clients, and a transient datastore mechanism for
transporting reports, PLM XML, and other nonvolume data between the
enterprise and client tiers.

FMS file caching enables placing the data close to the user, while maintaining a
central file volume and database store.

filter rules (PLM XML)

Rules that allow a fine level of control over which data is translated, in PLM XML
format, along with the primary objects by specifying that a user-written function be
called to determine the operation applied against a specified object.
find number
Number that identifies individual occurrences (or groups of occurrences) within a
single-level assembly. Components are ordered by find number within an assembly.
fixed default
Default value for an option (for example, engine = 1200). A fixed default is attached
to an item revision but is global to the BOM loaded in a Structure Manager window.
Compare with derived default.
FMS
See File Management System (FMS).
folder
Graphical representation of an aggregation of objects, such as a group, class, or
subclass. For easy distinction in the class hierarchy, each of these aggregations has
a different type of folder icon associated with it: a group folder icon, a class folder
icon, or a subclass folder icon.
form
Teamcenter workspace object used to display product information (properties) in a
predefined template. Forms are often used to create an electronic facsimile of a
hardcopy form in Teamcenter. See also master form.
four-tier architecture
Teamcenter architecture that includes four tiers: resource tier, client tier, Web tier,
and enterprise tier. Contrast with two-tier architecture.
four-tier deployment
Deployment of the Teamcenter four-tier architecture. The Web tier, enterprise tier,
resource tier, and client tier can each be hosted on the same or separate computers.
G
GDE
See generic design element.
generic design element
BOM item that cannot have different revisions. See also feature.

A-6

Server Customization Programmers Guide

PLM00074 J

Glossary

group
Type of class that does not have a list of attributes associated with it; highest level
in the classification hierarchy.
H
harness
Assembly of insulated conductors formed to a predetermined pattern or
configuration; also called a wiring harness.
hierarchy
Structure in which each node can have only one parent but possibly multiple siblings
and children.
I
imprecise assembly
Single-level assembly that has items as the components. The revision is determined
by the revision rule settings. Compare with precise assembly.
instance
Single data object that is associated to a class. The instance can correspond to a
line in the BOM.
Integration
Active-mode relationship between an application and Teamcenter in which
Teamcenter is brought into the application. The application drives Teamcenter
to provide the functionality, such as implicit checkout when data is modified, and
reading and writing data directly from Teamcenter in a secured way. Data is
exported (pushed) and imported (pulled) as needed.
interface port
Single access point to the functionality of a piece of equipment, for example, a USB
port that provides an interface to a computer.
internal extension
Extension delivered as part of the Teamcenter product, also known as a canned
method.
item
Workspace object generally used to represent a product, part, or component. Items
can contain other workspace objects including other items and object folders.
item revision
Workspace object generally used to manage revisions to items.
L
Lifecycle Visualization
Visualization components available in the rich client, the thin client, and as a
stand-alone application. A scalable solution for the viewing and analysis of 2D and
3D product data, Lifecycle Visualization is available in a number of configurations
to meet the requirements of different organizations.

PLM00074 J

Server Customization Programmers Guide

A-7

Glossary

Appendix A

List of Values (LOV)

Pick list of values accessed by end users from a menu at the end of a data field.
LOVs ensure consistent data entries in the rich client.
LOV
See List of Values (LOV).
M
manufacturing bill of materials
Defines how the product is manufactured, rather than how it is designed. Compare
with design bill of materials.
master form
Teamcenter workspace object used to display product information (properties) in
a predefined template. Master forms are used to display product information in
a standardized format.
Mechatronics
Integration of mechanical engineering with electronics and intelligent computer
control in the design and manufacture of products and processes.
Multi-Site Collaboration
Teamcenter capability that allows the exchange of data objects among several
Teamcenter databases. Transfer of objects among databases is controlled by daemon
processes running on designated servers. Objects are replicated by exporting them
from their original database and importing them into the requesting database.
Configuration of Multi-Site Collaboration is optional.
My Teamcenter
In the Teamcenter rich client and thin client, application that is the main access
point for managing product information. My Teamcenter provides the functionality
for creating objects in the Teamcenter database, querying the database for objects,
checking in and checking out objects, and managing tasks. Users can also open
objects, automatically launching the related application.
Each user has a personal My Teamcenter window that displays product information
as graphical objects. Although users share product information across the enterprise,
they organize this information individually in personal workspaces.
N
named ACL
Named group of access controls. See also access control list (ACL).
named reference
File types that are managed by a dataset. Datasets are the only workspace objects
that use named references.
node
Point of interest in a harness. It may represent the beginning or end of a segment.

A-8

Server Customization Programmers Guide

PLM00074 J

Glossary

note
Assembly-related textual data associated with an occurrence. A note specifies a
value associated with the assembly-component relationship, for example, the torque
value for a bolt of 10 Ft Lb in one assembly and 15 Ft Lb in another assembly.
note type
Type created by the system administrator that is associated with an occurrence in a
product structure and enables users to specify a note.
NX Remote Manager
See NX Remote Manager.
NX Remote Manager
Teamcenter component for managing the import and export of documents into
Teamcenter. NX Remote Manager is a common component across integrations that
include applications in fields such as CAE and ME.
O
occurrence
Hierarchical structure relationship between the immediate parent assembly and
its child component item or item revision in a precise assembly. Sometimes called
relative occurrence.
Organization
Teamcenter application that enables a system administrator to create and manage
critical Teamcenter files and database entries. It is the point of access for creating a
companys virtual organization and for performing system administration activities
such as volume creation, maintenance, and site administration. Organization
enables creation and management of person, user, role, and group definitions;
definition of the hierarchical structure of the Teamcenter organization; management
of data volumes; and establishment and maintenance of Teamcenter sites.
owner
User that owns an object, initially the user who created it. Ownership can be
transferred from the owner to another user. An object owner usually has privileges
that are not granted to other users (for example, the privilege to delete the object).
owning group
Group that owns an object, usually the group of the user creating the object. Because
users commonly share data with other members of a group, additional privileges may
be granted to the owning group (for example, the privilege to write to the object).
owning site
Multi-Site Collaboration site where the master object resides. The owning site is the
only site where the object can be modified.
P
persistent object manager (POM)
Interface between Teamcenter objects and the Relational Database Management
System (RDBMS). The persistent object manager provides definition of classes
by inheritance from other classes and definition of attributes, manipulation of
in-memory objects and support for their saving and retrieval to and from the
underlying RDBMS, support for applications accessing the same data concurrently,

PLM00074 J

Server Customization Programmers Guide

A-9

Appendix A

Glossary

protection against the deletion of data used by more than one application, and
support for the access control lists attributed to objects.
person
Definition containing real-world information about each Teamcenter user, such as
name, address, and telephone number. Person definitions are stored as simple text
strings so that they can be easily changed and updated. The name must be unique.
piece part
Part with no structure (no associated BOM view revision).
PLM XML
Siemens PLM Software format for facilitating product life cycle interoperability
using XML. PLM XML is open and based on standard W3C XML schemas.
Representing a variety of product data both explicitly and via references, PLM
XML provides a lightweight, extensible, and flexible mechanism for transporting
high-content product data over the Internet.
POM
See persistent object manager (POM).
port
Occurrence of an interface port that represents the access point of a functional
module in a given context, for example, a USB 2.0 port on a computer processor.
precise assembly
Single-level assembly that has item revisions as the components. The item revision
is configured by a precise entry in a revision rule. Compare with imprecise assembly.
preference
Configuration variable stored in a Teamcenter database and read when a Teamcenter
session is initiated. Preferences allow administrators and users to configure many
aspects of a session, such as user logon names and the columns displayed by default
in a properties table.
process
Automation of a business procedure, describing the individual tasks and task
sequences required to complete a business procedure.
product
Item or assembly (hierarchy of components and subassemblies) to be manufactured.
product structure
Hierarchy of assembly parts and component parts with a geometric relationship
between them, for example, a bill of materials (BOM). Variant and revision rules
define the generic BOM. This BOM can then be loaded to display the configured
variant.
properties file
File containing the attributes (keys and values) that specify how an application is to
behave in the Teamcenter rich client.
pseudofolder
Special container in Teamcenter that stores and displays item and item revision
relations in My Teamcenter. See also smart folder.

A-10

Server Customization Programmers Guide

PLM00074 J

Glossary

R
registry file
Properties (.properties) file that contains the user-defined configuration settings
(keys and values) that are relative to how the application displays and performs
in the Teamcenter rich client. Each application registered in the rich client has a
.properties file known as a registry file.
relation
Description of an association between a Teamcenter object and a piece of information
that describes or is related to the object.
resource
Item used to perform an operation or define a process. Examples of resources include
robots, tools, and machines. Both standard equipment and custom tools can be
identified as resources.
resource tier
Teamcenter architectural tier comprising the database server, database, file servers,
and volumes.
revision rule
Parameter set by the user that determines which revision of an item is used to
configure product context.
rich client
Java-based user interface to Teamcenter installed on user workstations. The rich
client accesses Teamcenter databases using a remote or local server. Compare to
thin client.
root
Starting point of a hierarchy. Hierarchies are usually displayed as hanging trees
with the root of the structure at the top and the leaves at the bottom.
route
Course taken by wire or connection from a starting point to a destination.
rule handler
Handler used to integrate workflow business rules into Enterprise Process Modeling
processes at the task level. Rule handlers attach conditions to an action. See also
task handler.
S
Security Services
Services that eliminate prompts for logon credentials when users switch Teamcenter
products within a user session. Authentication is performed by an external identity
service provider, such as lightweight directory access protocol (LDAP), instead of
the Teamcenter product. At a site that deploys multiple Teamcenter products and
Security Services, users log on once to access all participating Teamcenter products.
segment
Section of a connection where no intermediate electrical contacts appear.

PLM00074 J

Server Customization Programmers Guide

A-11

Appendix A

Glossary

server
System software component that performs a specifically defined set of software
services on behalf of one or more clients. In a typical Teamcenter installation,
servers are centralized on dedicated hosts that support a large number of clients.
Clients are distributed on hosts connected to the servers via various networking
techniques. See also client.
server exits
Exit points from standard Teamcenter functionality to Java. These exit points are
also known as user services. Use them when you want to call your functions from
Java in the Teamcenter rich client.
server manager
Process that manages a pool of Teamcenter server processes in a deployment of
the four-tier architecture. The server manager starts and times out a configurable
number of server processes to communicate with the Teamcenter database. A
server assigner process assigns available server processes to user sessions. The
server manager communicates with the Web tier application using either TCP or
multicast protocol.
signal
Physical representation of a message or an information flow being generated,
processed, or conveyed within an electrotechnical system.
site
Individual installation of Teamcenter comprising a single Teamcenter database,
all users accessing that database, and additional resources such as hardware,
networking capabilities, and third-party software applications (tools) required to
implement Teamcenter at that site.
site ID
Unique identifier of a Teamcenter site. The site ID is used to generate internal
identifiers for Teamcenter objects that must be unique throughout an enterprise.
Once established, site IDs should not be modified.
site name
Unique name of a Teamcenter site stored in the database as a user-defined character
string.
smart folder
Pseudofolders configured in a hierarchical structure used to apply hierarchical levels
of filtering to project data. See also pseudofolder.
SQL
See Structured Query Language.
structure
Representation of multiple objects and their interdependencies. For example, a
classification structure represents classes and their inheritance dependencies, and
an assembly structure represents how components and subassemblies are associated
to build up an assembly. The structure can be viewed in several applications,
including Structure Manager, Manufacturing Process Planner, Part Planner,
Multi-Structure Manager, and Resource Manager.

A-12

Server Customization Programmers Guide

PLM00074 J

Glossary

In Resource Manager, most structures are hierarchical. For example, they acquire
the form of a tree where each node can have only one parent but multiple siblings
and children.
Structured Query Language
ANSI standard command and embedded language for manipulating data in a
relational database.
Structure Manager
Teamcenter application that enables creation of generic product structures that can
be configured to show the product structure that is in production, effective on a
certain date, used by a particular customer, and so forth. Structure Manager enables
creation and modification of a product structure and its associated occurrence data,
display of a product structure in a multilevel indented format, and viewing graphics
tightly coupled to the structure for easy identification of a component by location in
the structure or in the embedded viewer.
subclass
In the Classification Search Dialog, subclass instances represent a subset of
attributes corresponding to a class. Subclasses inherit the attributes of their parent
classes. Unlike classes, which inherit every attribute of their parent classes and
cannot be edited, users can define the inherited attributes assigned to a subclass.
substitute
Component that can be used interchangeably within an occurrence, typically for
manufacturing purposes. The preferred substitute is displayed in the structure.
system administrator
Teamcenter user who is a member of the system administration group.
T
task (workflow)
Fundamental building block used to construct a process. Each task defines a set of
actions, rules, and resources used to accomplish that task.
task handler
Small Integration Toolkit program or function. Handlers are the lowest level
building blocks in Enterprise Process Modeling. They are used to extend and
customize tasks. There are two kinds of handlers: action handlers and rule handlers.
See also action handler and rule handler.
Teamcenter application root directory
Directory location of the Teamcenter shared binary executables. The TC_ROOT
environment variable defines this location. Generally, the contents of this directory
change only with a new version of Teamcenter.
Teamcenter data directory
Directory location of the Teamcenter shared data subdirectories and files. The
TC_DATA environment variable defines this location. Each data directory is
associated with a single database instance.
Teamcenter option
See preference and user preference.

PLM00074 J

Server Customization Programmers Guide

A-13

Glossary

Appendix A

thin client
Teamcenter user interface that provides a streamlined browser-based view of product
information stored in a Teamcenter database. The thin client is configured in the
Web tier, which creates and serves its Web pages to the client. Compare to rich client.
top level
Object at the root of a product structure where a process plan is being developed.
The top level can be either an end product being manufactured or a subassembly
used in the end product (for example, an engine for a tractor where the tractor is
the end product).
transfer mode
Objects composed of rules that configure PLM XML import and export operations.
Transfer mode allows users to import and export data with little knowledge other
than the name of the transfer mode object.
two-tier architecture
Teamcenter architecture that includes a resource tier and a client tier. The resource
tier comprises the database server and database. The client tier comprises the
Teamcenter rich client, third-party applications that integrate with the rich client,
and a local server. This architecture supports only the Teamcenter rich client.
Contrast with four-tier architecture.
U
user
Definition that is the mechanism by which Teamcenter identifies and interacts with
each user. User definitions contain a name (derived from the person definition), user
ID, operating system name, and password.
user exits
Exit points from standard Teamcenter end-user functionality to a C program. These
exit points are also known as custom hooks. Use them when you want to call your
customizations directly from a Teamcenter interactive session.
user preference
Teamcenter preference applying to a specific user.
V
value
Content of a field or variable. It can refer to alphabetic, numeric, or alphanumeric
data.
variant BOM
BOM configured by applying a variant rule.
variant condition
Condition set on an occurrence to specify the option values required to configure that
occurrence (for example, Load IF engine = 1200).
variant rule
Collection of option values used in determining the variant of the BOM to be
configured (for example, car type = GLS, engine = 1200, gearbox = manual).

A-14

Server Customization Programmers Guide

PLM00074 J

Glossary

view type
Attribute of a BOM view revision. The view type specifies the BOM view revisions
intended use (for example, design or manufacture). The view type distinguishes one
BOM view revision from another BOM view revision of the same item revision.
visualization
Ability to display a realistic, real time, graphical visualization of geometric data.
volume
Operating system directory controlled by Teamcenter and used to store the files
managed by Teamcenter. When a user performs an action that causes Teamcenter
to create a file, the file is created in the Teamcenter volume. Users cannot directly
access the files in Teamcenter volumes; they must do so via a Teamcenter session.
W
Web tier
Teamcenter architectural tier that comprises a Java application running in a Java
2 Enterprise Edition (J2EE) application server. The Web tier is responsible for
communication between the client tier and enterprise tier.
workflow
Automation of the concept that all work flows through one or more business
processes to accomplish an objective. Using workflow, documents, information, and
tasks are passed between participants during the completion of a particular process.
Workflow Designer
Teamcenter application that enables administrators to graphically design workflow
process templates, incorporating company business practices and procedures into
the templates. Teamcenter users initiate workflow processes using these templates.
world
All users regardless of group or role.

PLM00074 J

Server Customization Programmers Guide

A-15

Index

A
Action handlers
Infinite loops . . . . . . . . . .
Overview . . . . . . . . . . . . .
Perform . . . . . . . . . . . . . .
Writing . . . . . . . . . . . . . .
Action rules . . . . . . . . . . . .
Adding a service . . . . . . . . .
Allocation object . . . . . . . . .
AllocationMap object . . . . . .
Assemblies, exporting . . . . .
Attachments . . . . . . . . . . . .
Attributes
Expressions . . . . . . . . . . .
Manipulation . . . . . . . . . .
Audit Manager . . . . . . . . . .
Autocomputing Classification
values . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

4-171
4-159
4-171
4-163
4-141
. . 3-2
. 4-75
. 4-75
4-107
4-162

.......
.......
.......
attribute
.......

. 4-50
. 4-39
4-150
. 4-72

B
b_curve class . . . . . . . . . . . . . .
Basic concepts
Server . . . . . . . . . . . . . . . . . .
Server customization . . . . . . .
Basic tasks
Server customization . . . . . . .
Services . . . . . . . . . . . . . . . .
Batch ITK programs . . . . . . . . .
Bill of materials, see BOM
BOM . . . . . . . . . . . . . . . . . . . .
Editing the BOM . . . . . . . . . .
Occurrence sequencing . . . . . .
Occurrences . . . . . . . . . . . . . .
Options . . . . . . . . . . . . . . . . .
Producing a report . . . . . . . . .
Product structure relationship
Variations . . . . . . . . . . . . . . .
BOM compare
Aggregate element uniqueness
Auto pack . . . . . . . . . . . . . . .
Cache method type . . . . . . . . .
Caching . . . . . . . . . . . . . . . .
Column output order . . . . . . .

PLM00074 J

. . . . . 4-77
. . . . . . 1-3
. . . . . . 2-1
. . . . . . 2-6
. . . . . . 3-2
. 4-204-21
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

. 4-94
. 4-96
. 4-95
4-101
4-101
. 4-94
4-130
4-101

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

4-112
4-110
4-114
4-110
4-114

Compare aggregate method type . . . 4-114

Compare object method type . . . . . . 4-114
Defining a BOM compare . . . . . . . . 4-107
Display elements . . . . . . . . . . . . . . 4-112
Element application flags . . . . . . . . 4-113
Element display aliasing . . . . . . . . 4-110
Element display suppression . . . . . . 4-110
Element naming . . . . . . . . . . . . . . 4-110
Element ordering modifier . . . . . . . 4-113
Execution . . . . . . . . . . . . . . 4-111, 4-115
Free cache method type . . . . . . . . . 4-114
Functions . . . . . . . . . . . . . . . . . . . 4-107
Method types . . . . . . . . . . . . . . . . . 4-114
Mode . . . . . . . . . . . . . . . . . . . . . . 4-108
Nonproperty elements . . . . . . . . . . 4-115
Object output order . . . . . . . . . . . . 4-113
Output . . . . . . . . . . . . . . . . . . . . . 4-118
Output suppression . . . . . . . . . . . . 4-120
Performing . . . . . . . . . . . . . . . . . . 4-117
Report output . . . . . . . . . . . . . . . . 4-119
UI suppression . . . . . . . . . . . . . . . 4-110
UIF name method type . . . . . . . . . . 4-114
UIF value method type . . . . . . . . . . 4-114
User exits . . . . . . . . . . . . . . . . . . . 4-118
Virtual unpack . . . . . . . . . . . . . . . 4-110
Visitor . . . . . . . . . . . . . . . . . . . . . 4-120
Briefcase . . . . . . . . . . . . . . . . . . . . . 4-145
Build . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Business Modeler IDE
Services . . . . . . . . . . . . . . . . . . . . . . 3-1
Business objects . . . . . . . . . . . . . . . . . . 1-7
Business rule handlers . . . . . . . . . . . 4-162
C
C++ coding . . . . .
Check reference .
Class
Hierarchy . . . .
Instances . . . .
Classification . . .
Clients, services .
Compatibility . . .
Compiling
Batch programs

. . . . . . . . . . . . . . . . . 2-8
. . . . . . . . . . . . . . . . 4-42
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

. 4-4
4-38
4-72
. 3-3
. 1-2

. . . . . . . . . . . . . . . . 4-21

Server Customization Programmers Guide

Index-1

Index

Commands . . . . . . . . . . . . . . . . . . . 4-15
Connection object . . . . . . . . 4-75, 4-80, 4-82
Connection_Terminal object . . . . . . . . . 4-75
Conventions, syntax definitions . . . . . . . 4-1
Copy instance . . . . . . . . . . . . . . . . . . . 4-36
Create
Instance . . . . . . . . . . . . . . . . . . . . . 4-35
Operation . . . . . . . . . . . . . . . . . . . . 2-10
CreateInput API . . . . . . . . . . . . . . . . . 2-10
Custom
Exits . . . . . . . . . . . . . . . . . . . . . . . . 4-21
Library . . . . . . . . . . . . . . . . . . . . . . 4-22
CUSTOM_execute_callbacks . . . . . . . . 4-26
CUSTOM_execute_callbacks_from_
library . . . . . . . . . . . . . . . . . . . . . . . 4-27
CUSTOM_register_callbacks . . . . . . . . 4-26
CUSTOM_register_exit . . . . . . . . . . . . 4-26
Customization
Hints . . . . . . . . . . . . . . . . . . . . . . . 4-31
Memory allocation . . . . . . . . . . . . . . 4-31
Messages . . . . . . . . . . . . . . . . . . . . 4-32
Method arguments . . . . . . . . . . . . . . 4-31
Value caching . . . . . . . . . . . . . . . . . 4-33
D
Data Exchange . . . . . . . . .
Data manipulation services
Class of instances . . . . . .
Copy instance . . . . . . . .
Create instance . . . . . . .
Delete instances . . . . . . .
Inquiries to find instances
Instances of class . . . . . .
Load instances . . . . . . . .
Order instance . . . . . . . .
Reference of instance . . .
Refresh instances . . . . . .
Save instances . . . . . . . .
Unload instance . . . . . . .
Data model
Customization framework
Structure . . . . . . . . . . .
Terms . . . . . . . . . . . . . .
Data types . . . . . . . . . . . .
Debug . . . . . . . . . . . . . . .
Delete instances . . . . . . . .
Dynamic participants . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

. 2-12-2
. . . . 1-3
. . . . 1-7
. . . . 4-5
4-6, 4-11
. . . 4-38
. . 4-159

.
.
.
.
.
.
.
.
.
.
.
.
.

4-144
4-35
4-38
4-36
4-35
4-38
4-39
4-38
4-36
4-38
4-38
4-37
4-36
4-37

EPM, see Enterprise Process Modeling

Errors
Customizing . . . . . . . . . . . . . . . . . . 4-70
Defining . . . . . . . . . . . . . . . . . . . . . 4-70
Handling . . . . . . . . . . . . . . . . . . . . . 4-14
Messages . . . . . . . . . . . . . . . . . . . . 1-11
Executing multiple customizations . . . . 4-25
Export objects . . . . . . . . . . . . . 4-1324-133
Object types . . . . . . . . . . . . . . . . . 4-133
Restrictions and responsibilities . . . 4-135
Route . . . . . . . . . . . . . . . . . . . . . . 4-134
Exporting
Assemblies to NX . . . . . . . . . . . . . . 4-107
Symbols . . . . . . . . . . . . . . . . . . . . . 4-18
F
Failure path . . . . . . . . . . . .
File relocation . . . . . . . . . . .
Filter rules . . . . . . . . . . . . .
Format of functions . . . . . . .
Function format . . . . . . . . .
Functionality object . . . . . . .
FunctionalityRevision object
4-794-80

. . . . . . . 4-159
. . . . . . . . 4-29
. . . . . . . 4-143
. . . . . . . . . 4-2
. . . . . . . . . 4-2
4-75, 4-794-80
. . . . . . . 4-75,

G
GDE object . . . . . . . . . . . . . . . . . . .
GDELink object . . . . . . . . . . . . . . .
GDEOccurrence object . . . . . . . . . . .
Generated code . . . . . . . . . . . . . . . .
Getting attributes of loaded instances
Getting started
Data-model-based customization . .
ITK customization . . . . . . . . . . . .
Server customization . . . . . . . . . .
Services customization . . . . . . . . .
Groups . . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.

.
.
.
.
.

4-75
4-75
4-75
. 2-3
4-41

.
.
.
.
.

.
.
.
.
.

. 2-1
. 4-1
. 1-2
. 3-1
4-42

H
.h files . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Harness model support . . . . . . . . . . . . 4-77
Hierarchical storage management . . . 4-152
Hierarchy of classes . . . . . . . . . . . . . . . 4-4
HSM, see Hierarchical storage management
I

E
Enterprise Process Modeling
Customizing . . . . . . . . . . . . . . . . . 4-162
Module . . . . . . . . . . . . . . . . . . . . . 4-157
Object model . . . . . . . . . . . . . . . . . 4-158

Index-2

Server Customization Programmers Guide

ICS_auto_compute_get_attr_prop .
ICS_auto_compute_get_attr_value
ICS_auto_compute_set_attr_prop .
ICS_auto_compute_set_attr_value
Import objects . . . . . . . . . . . . . . .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.

4-74
4-73
4-74
4-74
4-132

PLM00074 J

Index

Interface . . . . . . . . . . .
Object types . . . . . . . .
Restrictions . . . . . . . . .
Route . . . . . . . . . . . . .
Semantics . . . . . . . . . .
Include files . . . . . . . . . .
Initializing modules . . . .
Inquiries to find instances
Instances of class . . . . . .
Interface Port object . . . .
ITEM_id_size_c . . . . . . . .
ITEM_name_size_c . . . . .

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

. . . 4-138
. . . 4-133
. . . 4-137
. . . 4-136
. . . 4-136
. . . . . 4-4
. . . . 4-15
. . . . 4-39
. . . . 4-38
4-794-80
. . . . . 4-3
. . . . . 4-3

J
Jobs . . . . . . . . . . . . . . . . . . . . . . . . . 4-158
Journal files . . . . . . . . . . . . . . . . . . . . 4-12
L
libbase_utils library . . . . . . . .
libitk library . . . . . . . . . . . . . .
Libraries . . . . . . . . . . . . . . . .
libuser_exits.dll . . . . . . . . . . .
License agreement . . . . . . . . .
Linking
Batch programs . . . . . . . . . .
Stand-alone programs . . . . .
User exits in UNIX and Linux
User exits in Windows . . . . .
Load instances . . . . . . . . . . . .
Logging . . . . . . . . . . . . . . . . .
Writing warnings or errors . .
Longer class attributes . . . . . .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

1-10
1-10
1-10
4-18
. 1-2

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

4-21
4-19
4-16
4-17
4-36
4-13
1-11
. 4-3

M
mem.h header file . . . . . . . . . . . . .
Memory management . . . . . . . . . .
Messages
Defining . . . . . . . . . . . . . . . . . .
Modifying attributes in the database
Moving files . . . . . . . . . . . . . . . . .
Multi-Site Collaboration . . . . . . . .

. . . 1-10
. . . 4-15
..
.
..
..

. 4-70
. 4-40
. 4-29
4-147

.
.
.
.
.

.
.
.
.

N
Naming conventions of variables
Network object . . . . . . . . . . . . .
Network_Port object . . . . . . . . .
Node class . . . . . . . . . . . . . . . .
NX, exporting to . . . . . . . . . . . .
O
Operations

PLM00074 J

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

. 4-3
4-75
4-75
4-77
4-107

Create . . . . . . . .
Extend . . . . . . .
ORDER BY clauses
Order instance . . .

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

2-10
. 2-7
4-50
4-38

P
Participants . . . . . . . . . . . . . . . . .
Persistent Object Manager, see POM
PLM XML . . . . . . . . . . . . . . . . . .
Action rules . . . . . . . . . . . . . . . .
Filter rules . . . . . . . . . . . . . . . .
Setting the target path name . . .
Pointer variable . . . . . . . . . . . . . .
POM . . . . . . . . . . . . . . . . . . . . . .
attr_id . . . . . . . . . . . . . . . . . . .
Attribute . . . . . . . . . . . . . . . . . .
Attribute manipulation . . . . . . .
Check reference . . . . . . . . . . . . .
Class . . . . . . . . . . . . . . . . . . . .
Class of instances . . . . . . . . . . . .
class_id . . . . . . . . . . . . . . . . . . .
Concepts . . . . . . . . . . . . . . . . . .
Copy instance . . . . . . . . . . . . . .
Create groups . . . . . . . . . . . . . .
Create instance . . . . . . . . . . . . .
Create members . . . . . . . . . . . .
Create users . . . . . . . . . . . . . . .
Data manipulation services . . . . .
Delete groups . . . . . . . . . . . . . .
Delete instances . . . . . . . . . . . . .
Delete members . . . . . . . . . . . . .
Delete users . . . . . . . . . . . . . . .
Enquiry . . . . . . . . . . . . . . . . . .
Environment . . . . . . . . . . . . . . .
Errors . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . .
Getting attributes of loaded
instances . . . . . . . . . . . . . . .
Groups . . . . . . . . . . . . . . . . . . .
Index . . . . . . . . . . . . . . . . . . . .
Initialize groups . . . . . . . . . . . . .
Initialize members . . . . . . . . . . .
Initialize users . . . . . . . . . . . . . .
Inquiries . . . . . . . . . . . . . . . . . .
Inquiries to find instances . . . . . .
Instance . . . . . . . . . . . . . . . . . .
Instances of class . . . . . . . . . . . .
Load instances . . . . . . . . . . . . . .
Loading . . . . . . . . . . . . . . . . . . .
Log on . . . . . . . . . . . . . . . . . . . .
Modifying attributes in the
database . . . . . . . . . . . . . . . .
Order instance . . . . . . . . . . . . . .

Server Customization Programmers Guide

. . 4-159
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

4-138
4-141
4-143
4-144
. 4-15
. 4-33
. 4-41
. 4-34
. 4-39
. 4-42
. 4-33
. 4-38
. 4-41
. 4-33
. 4-36
. 4-42
. 4-35
. 4-42
. 4-42
. 4-35
. 4-43
. 4-38
. 4-43
. 4-43
. 4-49
. 4-47
. 4-47
. 4-48

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

4-41
4-42
4-34
4-43
4-43
4-43
4-44
4-39
4-34
4-38
4-36
4-70
4-47

. . . 4-40
. . . 4-38

Index-3

Index

Password . . . . . . . . . . . . . . .
Reference of instance . . . . . .
Refresh instances . . . . . . . . .
Rollback . . . . . . . . . . . . . . .
Save instances . . . . . . . . . . .
Set group . . . . . . . . . . . . . .
Set user status . . . . . . . . . . .
Setting attributes of loaded
instances . . . . . . . . . . . .
SQL . . . . . . . . . . . . . . . . . .
Starting . . . . . . . . . . . . . . .
Stopping . . . . . . . . . . . . . . .
System utilities . . . . . . . . . .
Tag . . . . . . . . . . . . . . . . . . .
Time-outs . . . . . . . . . . . . . .
Unload instance . . . . . . . . . .
Users . . . . . . . . . . . . . . . . .
Variable length array . . . . . .
POM enquiry . . . . . . . . . . . . .
API . . . . . . . . . . . . . . . . . . .
Attribute expressions . . . . . .
Basic concepts . . . . . . . . . . .
Building expressions . . . . . .
Class alias . . . . . . . . . . . . . .
class_alias . . . . . . . . . . . . . .
Creating queries . . . . . . . . .
DIFFERENCE set operator .
Escape character . . . . . . . . .
Expression . . . . . . . . . . . . .
FROM clause . . . . . . . . . . . .
Function expression . . . . . . .
GROUP BY clause . . . . . . . .
HAVING clause . . . . . . . . . .
INTERSECTION set operator
Join . . . . . . . . . . . . . . . . . .
Loading . . . . . . . . . . . . . . . .
Logical expression . . . . . . . .
ORDER BY clause . . . . . . . .
ORDER BY clauses . . . . . . .
POM_enquiry_countdist . . . .
POM_enquiry_cpid_of . . . . .
POM_enquiry_in . . . . . . . . .
POM_enquiry_lower . . . . . . .
POM_enquiry_not_in . . . . . .
POM_enquiry_substr . . . . . .
POM_enquiry_upper . . . . . .
Pseudo class . . . . . . . . . . . .
pseudo_class . . . . . . . . . . . .
SELECT attributes . . . . . . .
SELECT clause . . . . . . . . . .
Set expression . . . . . . . . . . .
Subqueries . . . . . . . . . . . . .
Supported operators . . . . . . .
UNION set operator . . . . . . .

Index-4

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. . . . 4-40
. . . . 4-48
. . . . 4-46
. . . . 4-46
. . . . 4-45
4-35, 4-41
. . . . 4-46
. . . . 4-37
. . . . 4-42
. . . . 4-41
. . . . 4-49
. . . . 4-56
. . . . 4-50
. . . . 4-50
. . . . 4-56
. . . . 4-54
. . . . 4-62
. . . . 4-51
. . . . 4-65
. . . . 4-54
. . . . 4-54
4-56, 4-59
. . . . 4-54
4-56, 4-61
4-56, 4-61
. . . . 4-64
. . . . 4-53
. . . . 4-70
. . . . 4-54
4-56, 4-60
. . . . 4-50
. . . . 4-68
. . . . 4-67
. . . . 4-68
. . . . 4-67
. . . . 4-68
. . . . 4-66
. . . . 4-67
. . . . 4-54
. . . . 4-63
. . . . 4-50
4-56, 4-58
. . . . 4-54
. . . . 4-61
. . . . 4-68
. . . . 4-65

Server Customization Programmers Guide

.
.
.
.
.
.
.

4-46
4-38
4-37
4-46
4-36
4-43
4-44

Where clause . . . . . . . .
WHERE clause . . . . . .
POM schema . . . . . . . . .
Port object . . . . . . . . . . .
Prerequisites . . . . . . . . .
Primary business objects .
Process Variable object . .
Product structure . . . . . .
BOM relationship . . . .
BOM view class . . . . . .
BOM view revision class
Classes . . . . . . . . . . . .
Model . . . . . . . . . . . . .
Note type class . . . . . .
Occurrences class . . . . .
View type class . . . . . .
Where used reports . . .
Properties
Introduction . . . . . . . .
PSConnection object . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. . . . . . . . 4-50
. . . . 4-56, 4-59
. . . . . . . . . 1-3
. . . . 4-80, 4-82
. . . . . . . . . 1-1
. . . . . . . . . 1-7
4-75, 4-824-83
. . . . . . . 4-122
. . . . . . . 4-130
. . . . . . . 4-122
. . . . . . . 4-123
. . . . . . . 4-122
. . . . . . . 4-129
. . . . . . . 4-128
. . . . . . . 4-124
. . . . . . . 4-127
. . . . . . . 4-129

. . . . . . . . . . . 1-8
. . . . . . . . . . 4-75

R
Reference of instance . . . .
Refresh instances . . . . . .
Registering
Custom callbacks . . . . .
Customizations . . . . . .
Run-time properties . . .
User exits customization
Reverse engineering . . . .
Revisioning scheme . . . . .
Route class . . . . . . . . . . .
RouteCurve object . . . . . .
RouteLocation object . . . .
RouteLocationRev object .
RouteNode object . . . . . .
RoutePath object . . . . . . .
RouteSegment object . . . .
Rule handlers . . . . . . . . .
Running ITK programs . .

. . . . . . . . . . 4-38
. . . . . . . . . . 4-37
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

4-23
4-25
4-28
4-23
. 1-2
4-31
4-77
4-75
4-75
4-75
4-75
4-75
4-75
4-164
. 4-20

Sample files . . . . . . . . . . . . . . . . . .
Save instances . . . . . . . . . . . . . . . .
Secondary business objects . . . . . . .
Segment class . . . . . . . . . . . . . . . . .
SELECT attributes . . . . . . . . . . . . .
Server
Basic concepts for customization . .
Basic tasks for customization . . . .
Enabling customization . . . . . . . .
Getting started with customization

.
.
.
.
.

.
.
.
.
.

1-11
4-36
. 1-7
4-77
4-50

.
.
.
.

.
.
.
.

.
.
.
.

2-1
2-6
2-6
2-1

PLM00074 J

Index

Services
Adding . . . . . . . . . . . . . . . . . . . . . . . 3-2
Basic tasks . . . . . . . . . . . . . . . . . . . . 3-2
Clients . . . . . . . . . . . . . . . . . . . . . . . 3-3
Enabling . . . . . . . . . . . . . . . . . . . . . . 3-1
Getting started . . . . . . . . . . . . . . . . . 3-1
Overview . . . . . . . . . . . . . . . . . . . . . . 3-1
Setting
Attributes of loaded instances . . . . . . 4-40
Target path name . . . . . . . . . . . . . 4-144
Signal object . . . . . . . . . . . . 4-75, 4-824-86
Subscriptions . . . . . . . . . . . . . . . . . . 4-154
Success path . . . . . . . . . . . . . . . . . . . 4-159
Supplier custom hooks . . . . . . . . . . . . . 4-21
Syntax definition conventions . . . . . . . . . 4-1
System
Logs . . . . . . . . . . . . . . . . . . . . . . . . 4-13
Utilities . . . . . . . . . . . . . . . . . . . . . 4-45
T
tag_t . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Tasks . . . . . . . . . . . . . . . . . . . . . . . . 4-158
TC_report_serious_error API . . . . . . . . 1-11
TC_write_syslog API . . . . . . . . . . . . . . 1-11
Teamcenter Import Export (TIE) . . . . 4-146
Teamcenter mechatronics process
management
API modules . . . . . . . . . . . . . . . . . . 4-77
API use . . . . . . . . . . . . . . . . . . . . . . 4-78
Fundamental objects . . . . . . . . . . . . 4-75
Harness model support . . . . . . . . . . . 4-77
Object model . . . . . . . . . . . . . . . . . . 4-76
Objects . . . . . . 4-75, 4-794-80, 4-824-86
Preferences . . . . . . . . . . . . . . . . . . . 4-76
Relationships . . . . . . . . . . . . . . . . . . 4-75
Traversal Engine module . . . . . . . . . . 4-130
Compiling . . . . . . . . . . . . . . . . . . . 4-132
Installing . . . . . . . . . . . . . . . . . . . 4-131
Linking . . . . . . . . . . . . . . . . . . . . . 4-132
Minimum requirements . . . . . . . . . 4-131
Programming . . . . . . . . . . . . . . . . 4-132
User exits . . . . . . . . . . . . . . . . . . . 4-131
U
Unload instance . . . . . . . . . . . . . . . . . 4-37

PLM00074 J

Unpublished APIs and extension

points . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Upgrading ITK programs . . . . . . . . . . . 4-20
User
Exits . . . . . . . . . . . 4-164-17, 4-23, 4-149
Overview . . . . . . . . . . . . . . . . . . . . . 4-42
USER_init_module method . . . . . . . . . 4-25
USER_is_dataset_exportable user
exit . . . . . . . . . . . . . . . . . . . . . . . . 4-149
V
Variable length array
Variables . . . . . . . .
Vendor management
Visual Studio . . . . .
Volume Management

.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

. 4-41
. . 4-3
4-151
. . 4-6
4-152

W
Warning messages . . . . . . . . . . . . . . . 1-11
Where
Clause . . . . . . . . . . . . . . . . . . . . . . 4-50
Used reports . . . . . . . . . . . . . . . . . 4-129
Workflow
Action handlers . . . . . 4-159, 4-163, 4-171
Attachments . . . . . . . . . . . . . . . . . 4-162
Business rule handlers . . . . . . . . . . 4-162
Customizing with Enterprise Process
Modeling object model . . . . . . . . 4-162
Dynamic participants . . . . . . . . . . . 4-159
Enterprise Process Modeling
module . . . . . . . . . . . . . . . . . . . 4-157
Enterprise Process Modeling object
model . . . . . . . . . . . . . . . . . . . . 4-158
Failure path . . . . . . . . . . . . . . . . . 4-159
Jobs . . . . . . . . . . . . . . . . . . . . . . . 4-158
Participants . . . . . . . . . . . . . . . . . . 4-159
Rule handlers . . . . . . . . . . . . . . . . 4-164
Success path . . . . . . . . . . . . . . . . . 4-159
Task model . . . . . . . . . . . . . . . . . . 4-157
Tasks . . . . . . . . . . . . . . . . . . . . . . 4-158
WSO_name_size_c . . . . . . . . . . . . . . . . 4-3

Server Customization Programmers Guide

Index-5