Teamcenter Engineering
Integration Toolkit Programmer’s
Guide
Publication Number
ENG00043 A
Teamcenter® 2005 SR1
engineering process management
Teamcenter Engineering
Integration Toolkit Programmer’s
Guide
This product is intended for use only described in this document. UGS
cannot be responsible for the proper functioning of undescribed features
and parameters.
Publication Number
ENG00043 A
Manual History
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 9
Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 9
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Teamcenter Engineering Documentation . . . . . . . . . . . . . . . . . . . . . . . . . 14
Submitting Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Software Copyright and Trademark Notices . . . . . . . . . . . . . . . . . . . . . . 14
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Variable Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Class Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
Initializing Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
Special Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Linking Standalone Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Running the Executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20
Batch ITK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21
Supplier Custom Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24
Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Mechatronics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
Mechatronics Fundamental Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Harness Model Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4
Mechatronics API Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4
API Use Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-5
Embedded Software Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-15
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index-1
Figures
Tables
This manual describes how to use the Integration Toolkit to customize Teamcenter®
Engineering. Teamcenter Engineering belongs to the UGS® portfolio of digital
product lifecycle management software and services.
Audience
The readers of this guide should be experienced Teamcenter Engineering system
administrators and programmers.
Organization
This manual contains the following chapters and appendixes:
Conventions
This manual uses the conventions described in the following sections.
A caution icon identifies practices that can either produce results contrary
to what you expect or result in damage to software or data.
Syntax Definitions
This manual uses a set of conventions to define the syntax of Teamcenter commands,
functions, and properties. Following is a sample syntax format:
harvester_jt.pl [bookmark-file-name bookmark-file-name ...]
[directory-name directory-name ...]
The conventions are:
Bold Bold text represents words and symbols you must enter exactly
as shown.
In the preceding example, you enter harvester_jt.pl exactly as
shown.
Italic Italic text represents values that you supply.
In the preceding example, you supply values for bookmark-file-name
and directory-name.
text-text A hyphen separates two words that describe a single value.
In the preceding example, bookmark-file-name is a single value.
[] Brackets represent optional elements.
... An ellipsis indicates that you can repeat the preceding element.
• You can access the printable manuals from the Teamcenter Engineering
Documentation CD-ROM. To view the PDF-formatted manuals, use Adobe
Acrobat Reader, downloadable free-of-charge from Adobe Systems Incorporated
at the following URL:
http://www.adobe.com
Acrobat Reader allows you to view these manuals online and print selected
pages, sections, or the entire manual. UGS grants permission for Teamcenter
Engineering users to print, duplicate, and distribute this documentation.
Submitting Comments
Portions of Teamcenter software are provided by third-party vendors. Special
agreements with these vendors require UGS to handle all problem reports
concerning the software they provide. Please submit all comments directly to UGS.
Please feel free to give us your opinion of the usability of this manual, to suggest
specific improvements, and to report errors. Mail your comments to:
UGS Technical Communications
4233 Lexington Avenue N., Suite 3290
Arden Hills, MN 55126-6198
U.S.A.
To submit an incident report, you can use the UGS GTAC online support tools at
the following URL:
http://support.ugs.com
1 Introduction to Integration
Toolkit Programming
1 Introduction to Integration
Toolkit Programming
This chapter defines the Integration Toolkit and describes the two parts of the
manual.
The Integration Toolkit (ITK) is a set of software tools that you can use to integrate
third-party or user-developed applications with Teamcenter. The ITK is a set of C
and C++ functions used directly by Teamcenter and NX.
The Integration Toolkit is a set of callable subroutines that act as a programmatic
interface to Teamcenter. It is the means by which both internal and external
applications interface with the Teamcenter core (including RDBMS) and the
Teamcenter front end (including the window management subsystem). Internal
applications are those supplied such as NX. External applications are those that
you decide to integrate into Teamcenter.
2. ITK Modules
This part describes the Teamcenter modules where you can use ITK to customize
your Teamcenter application.
The dataset_cleanup utility fails to print out trailing information about the log
file after it finishes processing anchors before it exits to the prompt. On Windows,
you do not know if it ended correctly or the location of the log file. Also, it does not
delete anchors with zero size.
This applies to all ITK programs, not those only involving datasets. The problem can
be resolved by setting the IMAN_KEEP_SYSTEM_LOG environment variable to 1.
This applies to Windows only.
I ITK Concepts
This part describes the basic concepts you should be familiar with to customize
Teamcenter with ITK.
2 Architecture Overview
2 Architecture Overview
Teamcenter is constructed in tiers. The lowest tiers are closest to the database
and file volumes and the highest tiers are closest to the user. The Teamcenter
architecture consists of the following tiers:
• Client tier
• Web tier
• Enterprise tier
• Resource tier
Client Tier
The client tier comprises the Teamcenter Engineering clients: the thin client and
rich client. For more information, see the Thin Client Help - DHTML and the Rich
Client Customization Programmer’s Guide.
Web Tier
The Web tier is a Java application that runs in a Java 2 Enterprise Edition (J2EE)
application server, such as BEAWebLogic, and is responsible for communication
between the client tier and enterprise tier. The Web tier application also includes
the Application Interface Web Service (AIWS) and Teamcenter Engineering Data
Integration Services Adapter.
Enterprise Tier
The enterprise tier comprises a configurable pool of Teamcenter Engineering C++
server processes and a server manager. The enterprise tier retrieves data from
and stores data in the database. A server manager manages a pool of Teamcenter
Engineering server processes. This is the tier where you use ITK programming to
customize Teamcenter Engineering on the server side.
Resource Tier
The resource tier comprises a database server, database, volumes, and file servers
with two file management systems.
• The Teamcenter File Management System (FMS) downloads and uploads file
data for the rich client, Teamcenter Visualization, and the thin client configured
with Teamcenter Visualization. It provides a file storage, caching, distribution,
and access system. Multi-Site Collaboration also uses FMS servers to transfer
data.
• import/export
• programmatically
Interactive access is accomplished through the forms and menus or through the
interactive dialogues of applications integrated within Teamcenter. Import/export
involves taking the data out of Teamcenter, accessing the data by any means at
your disposal and later, putting data back into the Teamcenter system. ITK also
provides programmatic access.
You accomplish file access through the ImanFile interface of the ITK when this is
available through TCFS. For FMS-based file access, use the FMS ITK interface. You
can use the file management functions in this module to interface into the operating
system I/O utilities.
The information in the database is stored in tables in a relational database and is
accessed using SQL. Only the POM should ever read from, or write data directly
to, Teamcenter tables. Other application programs can create and access their own
tables directly.
The POM is the tool that we provide for internal programmers, third parties,
and customers to define their own data types, create and access their own data,
and access simple Teamcenter data. To define data types, you normally use
administrative applications in the rich client, such as Schema Editor, Type, or
Business Modeler, rather than directly editing schemas or writing code (for more
information about these applications, see Schema Editor Help, Type Help, and
Business Modeler Help). It also presents an object-oriented view of data, rather than
the tabular view that SQL presents. Finally, it implements the locking, checking of
access rights, and referential integrity checks for the system.
At the highest semantic level, there are application level procedures for accessing
data. These procedures can potentially operate on many objects at once, and can
perform tasks other than just simple data reads and writes.
For example, an ITK procedure to add an attribute to a Configuration Management
(CM) object can actually cause a new object to be created in the database. References
must be added from this new object to the CM object and vice versa. Several POM
calls must be made to build a valid set of data. Those POM calls make even more use
of SQL to finally speak to the relational database in its terms of tables, rows and
values. In general, the POM should not be used to access object data for which
there are higher level ITK procedures.
3 Application Interfaces
3 Application Interfaces
This chapter briefly describes the application interfaces you can use to integrate
external applications with Teamcenter Engineering.
There are five application interfaces you can use to integrate external applications
with Teamcenter Engineering:
• Service-Oriented Architecture (SOA)
SOA allows different applications to communicate with one another using
services. SOA is appropriate for integrating separate applications with a loose
linkage and network-friendly APIs that do not need to be modified with every
release of Teamcenter Engineering. This is the preferred method of integrating
third party and client applications. Future releases will extend this interface
and provide tools so you can easily extend it. For more information about SOA,
see the Web Services Guide.
• Generic Shell
Generic Shell is a mechanism that Teamcenter Engineering uses to encapsulate
an application. Generic Shell intercepts application save commands and saves
data files in Teamcenter Engineering volumes instead of directly in the operating
system file structure. Generic Shell is appropriate for some kinds of very simple
integrations, and you can avoid programming altogether if you use this interface
carefully.
The user_edshell.c file in the /sample/examples directory shows how to
integrate an application into Teamcenter using the Generic Shell, in this case an
ASCII text editor. You can use the Teamcenter ITK to develop a new application
that is fully integrated with Teamcenter or it can be used to develop a shell for
an existing application.
This chapter begins with a brief description of objects in general, then progresses to
a discussion of the Teamcenter Object Model. It also provides information on the
various objects used in the Teamcenter system and how they are related.
Object Model
The model is described using a set of two basic relationship diagrams. One set
of relationships show the class hierarchy (taxonomy) and the other shows the
associations that exist between interacting objects in the system.
This is the legend for the class object diagrams that follow.
Item
In Teamcenter, items are the fundamental objects used to manage information.
Items provide an identification for physical or conceptual entities about which an
organization maintains information and audit/change control. Typical uses of items
are parts, documents, and equipment. In an engineering/product development
environment, parts are identified as items. An item has the following basic
information:
• ID
A unique identifier for an item.
• Name
A user defined name to describe the item.
• Type
A classification of items that allow different types of items to be treated
separately. For example, an item may be used to manage parts and equipment.
By implementing two item types, rules can be enforced based on the type of
items that are being manipulated.
The system, as delivered, provides a generic type called item. If you
need additional types, the system administrator can create them at
your site.
• Description
A text field of up to 240 characters used to describe the item.
Item Revision
Item revisions are used to reflect modifications to an item. The original item revision
is retained for historical purposes.
Each customer site defines its own procedures to determine how and when a
new item revision should be created.
• Revision
A unique identifier for an item revision.
• Name
A user-defined name to describe the item revision.
Relations
Organizations produce several documents that describe, are used by, or in some
way relate to an item. For the data to be understood, it has to be associated in a
meaningful way to the item or item revision. Teamcenter associates data to items
and item revisions using relations.
Relations describe how the data is associated to an item and item revision. A dataset
containing the CAD model, which defines an item revision, is a specification of the
item revision. Similarly, a standards document describing the fit, form, and function
of a particular drawing is a requirement for the item.
An item or item revision can be related to several other objects, including datasets,
forms, folders, and other items and item revisions. Each object associated to the item
represents various aspects of that item. A dataset containing stress test information
could be added by the engineer, while a form containing size and weight information
could be added by the specification engineer.
Teamcenter provides a basic set of relations. The relations between the object and
the item and item revision determines the rules enforced.
Additional relations and their associated rules are defined by your system
administrator.
• Master_form
The master_form relation associates a form to an item or item revision. This
form is a collection of attributes that describe the item or item revision. Rules
for this relation are as follows:
– An item can have only one master form. An item revision can have only
one master form.
– A form can have a master_form relation to only one item or item revision.
• Requirement
The requirement relation associates data to an item or item revision, such as
standards, which must be adhered to in a drawing, or technical requirements for
a part. Rules for this relation are as follows:
• Manifestation
The manifestation relation associates other related data to an item or item
revision. This data may, however, be necessary for information, such as analysis
of the competing ideas from which a part was originally conceived. The
manifestation relation also associates data to the item revision that contains
data derived from the specification data (such as tool paths). Rules for this
relation are as follows:
– An item or item revision does NOT need to have write access to add or
remove a manifestation relation to an object. A manifestation relation
can be added or removed from a released item or item revision.
• Specification
The specification relation associates data which defines the item revision.
Examples are CAD models for parts or word processor files for documents. Rules
for this relation are as follows:
• Reference
The reference relation associates any data to an item or item revision. Rules
for this relation are as follows:
– An item or item revision does not need to have write access to add or remove
a reference relation to an object. A reference relation can be added or
removed from a released item or item revision.
• Revision
The revision relation associates item revisions to the appropriate item. Rules
for this relation are as follows:
– An item must have write access to add or remove an item revision from
the item.
• BOMView
The BOMView relation associates the product structure to an item. Rules for
this relation are as follows:
– A BOMView relation can represent the product structure of only one item.
• BOMView Revision
The BOMView Revision relation associates a product structure revision to an
item revision. Rules for this relation are as followed:
Item Type
Types are used to specialize the behavior of Teamcenter objects. Datasets implement
the most extensive use of type. The dataset type is used to categorize datasets.
Examples of dataset types are a document, an NX part, and a spreadsheet. When
a document dataset type is opened, the word processor application associated to
this dataset type is opened. When an NX part dataset type is opened, the NX
application associated to this dataset type is opened. For each dataset type, the
available operations (for example print and open) are defined, as well as the specific
behavior of each operation.
Item types extend the ability to specialize the behavior of items. You may need
to distinguish between a part used in production and equipment used to produce
that part. Both may need to be an item, yet the information and business rules
surrounding these items are different.
The system, as delivered, provides a generic item type called item. If you
need additional types, they can be created by the system administrator
at your site.
Dataset Model
Figure 4-3 shows the RevisionAnchor that creates a new logical dataset.
Unique ID Enforcement
The unique ID enforcement is performed at the application level. Each time the
New→Dataset command is used to create a dataset, the Save As and Import
commands are used, or the dataset is edited using the Properties command,
the validation function is called to ensure the dataset ID (id) and revision (rev)
combination is unique within that specified dataset type.
Also, for each dataset type, if the dataset ID is created using the Assign button, a
separate counter generates the next unique id that is available for a standalone
dataset. This counter ensures the id and rev is unique within the same dataset type.
Form Model
Forms provide the ability to store customer defined attributes. Teamcenter provides
standard forms. Most of the forms used at a customer site, however, are modified to
capture the information unique to its business.
Forms can be stored as POM objects. Attributes in the forms can be set and retrieved
using Form ITK functions. Forms stored as POM objects can use the POM query
ITK functions in addition to the Form ITK functions. When a form is stored as a
POM object, the database schema must be updated to recognize the new POM object.
Figure 4-4 show a diagram of the form model.
The Dataset class is the workspace object that an end user sees in their workspace.
The shell or integrated application associates one or more other pieces of data to the
dataset. More often than not, this means associating files for existing applications.
Some applications require several files in order to run. When this is the case, a
named reference can be created for each file. The name of the reference is often the
extension of the file but does not have to be. A CAD system may have a file in which
it stores geometric data with a .gmd extension, finite element modeling data in a file
with a .fem extension, and drawing data in a file with a .drw extension.
For such a CAD system, you could find references named geometry, fem, and
drawing, or gmd/fem/drw as the shell chooses. If you use the extensions, users do
not have to change the reference names during import, since by default the import
assumes the reference names correspond to the file extensions.
The model shows that the named reference can refer to an ImanFile object or other
descendant class of the POM object. This means a shell can be implemented that
does not use the ImanFile object to store file data, but instead uses its own file
object to store such information. However, you should do this rarely since there is a
loss of integrity that is provided by the ImanFile object. However, the flexibility it
provides may be necessary in some cases.
The RevisionAnchor object is provided to support revisioning of datasets.
Whenever a dataset is created, a RevisionAnchor object is also created. This
object maintains a list of working revisions of the dataset. However, it is up to the
shell/integrated tool to use this facility. To use it, you must make revision copies
and then make changes to these copies.
Class Hierarchy
The information in this section describes the hierarchy of classes (taxonomy).
Understanding this hierarchy, or returning to it, helps with understanding the rest
of the Teamcenter model description, which shows relationships and gives a more
detailed description of individual classes.
Class objects have a meaningful hierarchy that relates to the Teamcenter layered
software architecture previously discussed. It is presented in an indented outline
form.
The following legend defines the mnemonic descriptions given in parenthesis in
figure 4-7.
AE Application Encapsulation
AOM Application Object Module
BOM Bill Of Materials
CR Cascade Release
EPM Enterprise Process Modeling
FL Folder Manager
FORM Forms
IMF Teamcenter Engineering File
ITEM Item
MAIL Teamcenter Engineering Mail
POM Persistent Object Manager
PS Product Structure
SA System Administration
UOM Unit of Measure
VM Teamcenter Engineering Volumes
WSOM Workspace Object
Figure 4-7 shows the more common classes in the hierarchy. For more information
about other classes, see the Schema Editor.
Object-Oriented Data
An object is a data structure. It is basically the same as an entity or an instance of a
class. A class defines a type of object, its attributes, and methods that operate on it.
For example, folder is a class in Teamcenter. It is defined to have a name, a
description, and a list of entries. These are the attributes of the folder class. When
a folder is instantiated, an actual folder object is created. It has attributes as
described here. There are also methods or functions defined for the folder class, such
as Insert and Remove.
Attributes in Teamcenter can be integer, float, boolean, string, date, tag, or arrays of
any of the above types.
The attributes in Teamcenter can have some of following characteristics:
Inheritance
A subclass inherits both attributes and methods from superclasses.
Multiple inheritance means that a class has two superclasses. That is, it inherits
the attributes and methods from two different classes. There are no instances of
multiple inheritance in Teamcenter.
A superclass may be a generalization of many similar classes. For example, the
WorkspaceObject superclass is a generalization for all of the classes whose
instances may be seen in the workspace (for example, in a folder). All of the
attributes and methods that are common to the Dataset, Folder, and other classes
are defined once in the WorkspaceObject superclass, rather than being defined
many times. Usually, generalizations are abstract or non-instantiable. This means
that the class exists for conceptual or convenience reasons, but you cannot actually
create an instance of one.
A subclass may be a specialization of another class. For example, the Envelope
subclass is a specialization of the Folder class. In this case, a new class is being
defined that is just like another one except for some additional attributes and/or
some specialized behavior such as a specialized method.
Object-Oriented Language
An object-oriented language is a programming language that has built in key
words or constructs that either force or facilitate object oriented programming.
For example, C++ is one, because it supports classes, objects, inheritance, and
polymorphism. The C language is not.
However, you can do object oriented programming with a non-object oriented
language; it is just harder. You can certainly have an object model with inheritance
of attributes and methods without using an object oriented language. This is what
we present through ITK.
Internally, much of Teamcenter is written in C++. This provides an easy way of
handling polymorphism. You can take advantage of this in the ITK as well. If you
want to execute a method on an object, you do not need to call a function specific
to that action-class pair. You may call any function with that action up the tree of
superclasses for the selected object. For example, if you want to ask the name of an
envelope, you do not need to call the EMAIL_ask_envelope_name function (in fact,
that function does not exist). You can call the WSOM_ask_name function two levels
up in the hierarchy instead. That function realizes that it was actually passed an
envelope and invokes the envelope’s method to get the name.
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Journal Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
System Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
This chapter describes the format of ITK functions as well as details about writing,
compiling, linking, and running ITK programs.
Format
All ITK functions have a standard format that attempts to give the most information
possible in a small space. A template is shown below, followed by a more detailed
description. All prototypes are located in include files named classname.h for the
class of objects that the functions operate on. For more information about specific
functions, see the Integration Toolkit Function Reference
The design intent for the format of ITK functions is to provide the maximum amount
of information in a small space. The standard format is:
int module_verb_class_modifier ( const type variable-name[dimension]
/* [I/O/OF] */ );
int Nearly all ITK functions return an integer error code. This
code can be passed to the EMH_get_error_string function.
module This is the module designator. Related classes are
grouped together in modules. For example, the Dataset,
DatasetType, Tool, and RevisionAnchor classes are all
handled by the AE module. Other examples of modules are
PSM, POM, FL, and MAIL.
verb This is the first key word describing an action to be taken on
an object or set of objects. Common actions are create, add,
remove, copy, set, and ask.
class This is the class name or an abbreviation of the class name.
The exceptions are for modules that only deal with one class,
like Workspace or modules that deal with many classes,
like WSOM and POM.
modifier This is a word or several words that give more description of
how the action of the verb applies to the class. For example,
in the RLM_update_af_status function, status indicates
what is being updated in the af (authorization folder).
const Input pointer variables which are not meant to be modified
normally are declared with a const to ensure that they are
not accidentally modified.
type This is the data type of the argument (for example, int,
tag_t*, or char***).
variable-name This is a variable name that is descriptive enough
so a programmer does not need to look it up in the
documentation.
dimension This value is normally specified for arrays where the
calling program is responsible for allocating space. They
are normally specified with a constant definition of the
form module_description_c. These constants should be
used in dimensioning arrays or looping through the values
of an array to make your programs more maintainable.
However, you may see the values of these constants in the
include files. This is useful so you do not establish naming
conventions that leads to name strings longer than can be
passed to the functions.
I/O/OF These characters indicate whether the particular argument
is input, output or output-free. Output-free means that the
function allocates space for the returned data and this space
should be freed with the MEM_free function.
Most typedefs and constants begin with the module designator just like the function
names to make it clear where they are meant to be used.
Class Hierarchy
Because Teamcenter is an object-oriented system, it is not necessary to have a
function for every action on every class. Usually, functions associated with a
particular class work with instances for any subclasses. For example, the FL_
functions for folders work with authorizations and envelopes. The AOM module
and the WSOM module consist of functions that correspond to the methods of the
POM_application_object and WorkspaceObject abstract classes respectively.
AOM functions work for all application objects and WSOM functions work for all
workspace objects.
When you create objects, an implicit lock is placed on the newly created
object. After you perform an AOM_save, it is important that you call
AOM_unlock.
The same mechanism described here also enables standard Teamcenter functions to
work on subclasses that you may define. For example, if you define a subclass of the
folder class, you can pass instances of it to FL functions.
Debugging
This section contains information on ITK debugging aids such as journal files and
log files.
Journal Files
Teamcenter optionally journals the calls to all of the ITK functions. This is in a
file called journal_file after the program is run. This file can be very useful in
finding out what your program has done and where it went wrong. There are 5
journaling flags in the system for the POM, PSM, RLM, SA, and CMMV modules
and ITK in general. For POM, use the POM_set_env_info function; otherwise,
use the xxx_set_journaling(int flag) function, where flag is equal to 0 (zero) for
off or not equal to 0 for on. You could have ITK and RLM journaling on if you are
working in that area and leave POM and PSM journaling off, ensuring that your
journal file does not get cluttered with uninteresting information. Figure 5-1 shows
how the POM logs input and output arguments. Input arguments are logged with
their values, output arguments are logged on the way in with their names and on
the way out with their values.
POM_describe_attrs ( 00650021, 4, /
@*
@* 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
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
System Logs
In general, the system log is less useful, but sometimes you may see a
POM_internal_error or something else that does not make sense to you. You can
look in the system log to understand what went wrong. For example, if your program
crashes you may not have an error message, but the end of the system log may show
what the program was trying to do just before crashing.
Logging
For more information on logging, see the Log Manager (LM) module reference
section in the Integration Toolkit Function Reference.
Error Handling
Teamcenter Errors
Teamcenter stores errors on a central error stack. An error may be posted at a
low level and each layer of the code handles the error reported by the level below,
potentially adding a new error of its own to the top of the stack to add more
contextual information to the exception being reported. This stack of errors is
what you see displayed in the Teamcenter error window in the user interface. ITK
functions always return the top error from the stack if there is one. If the call is
successful, ITK_ok is returned.
The Error Message Handler (EMH) ITK functions enable you to access the full
error stack and decode individual Teamcenter error codes into the internationalized
texts that are defined in the UIL code and displayed in the error windows at the user
interface. EMH ITK functions are defined in the emh.h header file. They give
the ability to store errors, access errors on the stack, and decode error codes into
internationalized text. For additional information on EMH functions, see the EMH
section in the Integration Toolkit Function Reference manual.
It is good practice to acknowledge that you have received and handled an
error reported by an ITK call by clearing the error store with a call to the
EMH_clear_errors function. However, if you do not do this it normally
does not cause a problem, as all initial errors should start a new stack with
a call to the EMH_store_initial_error function.
2. Log in to Teamcenter.
5. Update the CORBA call profiler. You can see the icct calls for the workspace
object operation.
If there are a larger number of network calls, check the rich client’s DOS window for
an invalid Unicode character error for this operation. The error looks like this:
DefaultValidationEventHandler: [FATAL_ERROR]: An invalid XML character
(Unicode: invalid-character) was found in the value of attribute
"attribute" and element is "element".
<TcResponse>
<TcCorbaResponse>
<Arg name="propertyUIFValueSet">
<Array><Entry>
<Array>
<Entry>
<Struct>
<Arg name="_discriminator" val="1"/>
<Arg name="string_value" val="003104-Arch Modeler Var Enh-Phase
2"/>
</Struct>
</Entry>
<Entry>
<Struct>
<Arg name="_discriminator" val="1"/>
<Arg name="string_value" val=""/>
</Struct>
</Entry>
<Entry>
<Struct>
<Arg name="_discriminator" val="1"/>
<Arg name="string_value" val="Item"/>
</Struct>
</Entry>
<Entry>
<Struct>
<Arg name="_discriminator" val="1"/>
<Arg name="string_value" val="Architecture Modeler Variability Enh
□ Phase II"/>
</Struc>
</Entry>
If you have an invalid Unicode character, you can use the code shown in figure 5-5 as
a template to create your own ITK utility to fix the problem:
#include <iman.h>
#include <emh.h>
#include <pom.h>
#include <WSO-object-header-file.h>
// for example, if the item description has an invalid
// Unicode character, you must use #include <item.h>
ifail = ITK_auto_login();
// Attempts an automatic login first by assuming sufficient
// data is available on the command line
ITK_set_journalling(TRUE);
// it only controls additional journalling that
// takes place inside your custom ITK code.
if(ifail != ITK_ok)
{
EMH_ask_error_text(ifail, &message);
printf("Error : Could not get User info : %d , %s \n",ifail,message);
MEM_free(message);
return ifail;
}
AOM_save(item_tag);
AOM_refresh(item_tag, false);
/* do clean up before exit..*/
ITK_exit_module(TRUE);
return ifail;
}
Memory Management
Frequently, memory is allocated by an 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> */
);
tag_t* tool_tags;
int tool_count;
int error_code;
int i;
else
Include Files
All ITK programs must include iman.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 astag_t, ITK_ok, and MEM_free.
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 manual tells you which header files
are required.
There is also an error include file for every module called module_errors.h or
sometimes classname_errors.h. These all contain error offsets from a value
assigned in the EMH_const.h file. One exception is POM which has its errors in
the 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
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 iman_ include files, thus enabling the Teamcenter
source code and yours to remain system independent. The files provided are:
• iman_ctype.h
• iman_errno.h
• iman_limits.h
• iman_math.h
• iman_stat.h
• iman_stdarg.h
• iman_sddef.h
• iman_stdio.h
• iman_stdlib.h
• iman_string.h
• iman_time.h
• iman_types.h
• iman_unixio.h
Initializing Modules
You must call the module initialization functions, 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.
{
tag_t dataset_tag;
int error_code;
{ if (dataset_tag == NULLTAG)
{ /*
* Could not find my special dataset, so go create one.
*/
error_code = AE_create_dataset_with_id (....
}
}
else
Compiling
Compile your program using the ANSI option. The ITK functions can also be called
from C++. Sample compile scripts are available in the IMAN_ROOT/sample
directory. Assuming the script name is compile, it can be used by executing the
following command.
IMAN_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$IMAN_INCLUDE
• SOLARIS
cc -KPIC -DSUN -DUNX -D_SOLARIS_SOURCE -DSYSV +w -Xc -O -I.
-I${IMAN_INCLUDE} -c filename.c -o filename.o
• Linux
gcc -c -fPIC -m64 -DPOSIX -I${IMAN_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 standalone program object is being compiled:
$IMAN_ROOT/sample/compile -DIPLIB=none filename.c
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 IMAN_ROOT/sample
directory.
If the script name is linkitk, you can execute the script with the following command.
$IMAN_ROOT/sample/linkitk -o executable-name filename.o
Additionally, this information only effects those building the ITK client programs.
Once linked correctly, the Oracle (archive) libraries required are linked into the
program statically and therefore do not depend upon the version of Oracle libraries
available at the point of using ITK programs.
a. Copy all of the files that you want to modify (user_gsshell.c in the following
example):
$ cp $IMAN_ROOT/sample/examples/user_gsshell.c .
5. Compile your library objects and move them into the library directory:
$ $IMAN_ROOT/sample/compile *.c
$ cp *.o ../user_exits
7. You now have a new libuser_exits.s file. Set the IMAN_USER_LIB command
to get Teamcenter to use it:
$ export IMAN_USER_LIB=’pwd’
$ $IMAN_BIN/iman
You see your printf messages after the Teamcenter copyright messages.
a. Copy all of the files that you want to modify (the user_gsshell.c file in the
following example):
$ cp $IMAN_ROOT/sample/examples/user_gsshell.c .
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.
%IMAN_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
%IMAN_ROOT%\sample\link_user_exits
7. You now have new libuser_exits.dll and libuser_exits.lib files. Set the
IMAN_USER_LIB command to get Teamcenter to use it.
To run standalone 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.
3. Enter #include <libuser_exits_undef.h> at the end of the header file after all
declarations (within any multiple include prevention preprocessing).
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
standalone code against the libuser_exits.lib file.
Now you can compile and link as normal (in other words, compile with
–DIPLIB=libuser_exits).
3. Register your ITK functions in the user_server_exits.c file. For example, if you
wanted to register an ITK function called ACME_PasteRevToNewstuff in the
user_server_exits.c file, the file would look like figure 5-6:
#include <user_server_exits.h>
#include <acme_userservice.h>
/*
* This function registers the server side user defined functions for the
* CORBA server
*/
iNumberOfArgs = 2
piArgTypes = (int*) SM_alloc_persistent (iNumberOfArgs * sizeof (int));
piArgTypes[0] = USERARG_STRING_TYPE;
piArgTypes[1] = USERARG_STRING_TYPE;
USERSERVICE_register_method( "ACME_PasteRevToNewstuff",
ACME_PasteRevToNewstuff,
iNumberOfArgs,
piArgTypes,
USERARG_TAG_TYPE);
return (status);
}
4. Compile your code and the user_server_exits.c file using the compile.bat
script in the IMAN_ROOT\sample directory with the following command:
%IMAN_ROOT%\sample\compile -DIPLIB=libserver_exits
user_server_exits.c your-source-code.c
You can then call your ITK functions from the rich client. For example, if you
wanted to call the ACME_PasteRevToNewstuff function from a JPanel within an
application, the code would look like figure 5-7:
package com.acme.newapp;
import java.lang.Object;
import java.awt.*;
import javax.swing.*;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import com.ugsolutions.aif.*;
import com.ugsolutions.aif.kernel.*;
import com.ugsolutions.iman.kernel.*;
import com.ugsolutions.util.*;
application = app;
session = (IMANSession)application.getSession();
try
{
service = (IMANUserService)session.getUserService();
}
catch( IMANException e )
{
}
JtextPane1.setCaretColor(Color.red);
JtextPane1.setText(“Welcome”);
JtextPane1.setForeground(Color.magenta);
objs[0] = itemID;
objs[1] = revID;
try
{
component = (IMANComponent) service.call( “ACME_PasteRevToNewstuff”, objs);
}
catch( IMANException e )
{
MessageBox msgBox = new MessageBox( e );
msgBox.setModal( true );
msgBox.setVisible( true );
}
}
public NewAppApplicationPanel()
{
try
{
jbInit();
} catch( Exception e )
{
e.printStackTrace();
}
}
Batch ITK
You can create batch ITK programs that are executed on a command line. Batch
programs log into the Teamcenter database using information on command line,
perform some actions, and then exit.
#include <iman.h>
#define WRONG_USAGE 100001
void dousage()
{
printf("\nUSAGE: template -u=user -p=password -g=\"\" \n");
return;
}
if ( (help) )
{
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);
SM_free(s);
return status;
}
else printf("Logon to ’template’ succesful as %s.\n", usr);
ITK_exit_module( TRUE);
return status;
• IMAN_INCLUDE
The Teamcenter include files directory
• USER_INCLUDE
Includes any user-specific header files
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
The compile and linkitk scripts are Teamcenter-specific scripts and are available
in the IMAN_ROOT/sample directory.
Introduction
Custom hooks allow nonconflicting customizations to co-exist.
Environment
All the server-side customizations of the site, including user_exits and server_exits
are built in the form of a single library, called site-name.dll/so/sl.
For example, if the site name is tceng_cust1, the library is tceng_cust1.dll/so/sl.
The custom library site-name.dll/so/sl is linked with libuser_exits. Use the
link_custom_exits/link_customer_exits.bat file from the IMAN_ROOT/sample
directory. All custom standalone 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
IMAN_customization_libraries preference. Make sure the prefix and the library
prefix mentioned above are the same. Set the preference in the Options dialog
window, accessed from the Edit menu in My Navigator. For additional information
on setting preferences, see My Navigator Help.
2. Copy all your user exits and server exits customization code to this directory.
5. If you are using Windows, copy the .dll and .PDB files to the directory that
contains the .dll files. For example,
copy tceng_cust1.dll %IMAN_ROOT%\\bin\\.
copy tceng_cust1.pdb %IMAN_ROOT%\\bin\\.
If you are using UNIX, copy the shared library to the IMAN_USER_LIB
directory or put the tceng_cust1 directory in the shared library path
(Hewlett-Packard: SHLIB_PATH, Solaris: LD_LIBRARY_PATH).
#include <custom.h>
#include <user_exits.h>
#include your-include-files
extern DLLAPI int tceng_cust1_register_callbacks()
{
USER_register_custom_exit (“site-name”, “Base User Exit Function”, (CUSTOM_EXIT_ftn_t)
your-custom-function-name);
}
• 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.
Figure User Exits Customization Example shows an example with the following
conditions:
• The site name is tceng_cust1.
tceng_cust1_register_calls.c:
#include <custom.h>
#include <user_exits.h>
#include <tceng_cust1_dataset.h>
#include <tceng_cust1_register_callbacks.h>
#include <tceng_cust1_register_callbacks.h>
extern DLLAPI int tceng_cust1_register_callbacks()
{
USER_register_custom_exit (“tceng_cust1”, “USER_new_dataset_name”, (CUSTOM_EXIT_ftn_t)
TCENG_CUST1_new_dataset_name);
}
tceng_cust1_register_callbacks.h:
extern DLLAPI int tceng_cust1_new_dataset_name (int *decision, va_list args);
tceng_cust1_dataset.c:
#include <tceng_cust1_register_callbacks.h>
#include <custom.h>
#include <custom.h>
#include <user_exits.h>
#include <tceng_cust1_serverexits.h>
#include <tceng_cust1_register_callbacks.h>
#include <your-include-files>
extern DLLAPI int tceng_cust1_register_callbacks()
{
USER_register_custom_exit (“tceng_cust1”, “USER_new_dataset_name”, (CUSTOM_EXIT_ftn_t)
TCENG_CUST1_new_dataset_name);
USER_register_custom_exit (“tceng_cust1”, “USERSERVICE_register_methods”,
(CUSTOM_EXIT_ftn_t)
TCENG_CUST1_register_userservices);
}
tceng_cust1_userservices.h:
extern int TCENG_CUST1_register_userservices(int *decision, va_list args);
tceng_cust1_ userservices.c:
extern in TCENG_CUST1_register_userservices( int *decision, va_list args)
{
/*
Expand the va_list using va_arg
As there are no arguments for USERSERVICE_register_methods(), no need to get any
variables.
*/
/*
if tceng_cust1 wants all other customizations to be executed, then set
*decision = ALL_CUSTOMIZATIONS;
elseif tceng_cust1 wants only its customization to be executed then set
*decision = ONLY_CURRENT_CUSTOMIZATION;
else if tceng_cust1 wants only base functionality to be executed, then set
*decision = NO_CUSTOMIZATIONS;
*/
}
5. The preference values should match the library names. For example,
the tceng_cust1 site should have the tceng_cust1.dll/sl/so file and the
tceng_cust2 site should have the tceng_cust2.dll/sl/so file.
6. The custom libraries of the tceng_cust1 and tceng_cust2 sites (which would
be tceng_cust1.dll/sl/so and tceng_cust2.dll/sl/so respectively) should be in
the library path:
• LD_LIBRARY_PATH for Solaris or Linux
Registering Customizations
There are four different functions you can use to register customizations, depending
on the situation.
CUSTOM_register_callbacks
It goes through each custom library registered in the Options dialog window, 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_ and USERSERVICE_ exits.
CUSTOM_register_exit
• context
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
Name of the USER_ or USERSERVICE_ exit for which the custom exit has to
be registered (for example, USER_new_dataset_name).
• custom_ftn
The name of the custom exit (a custom function pointer).
CUSTOM_execute_callbacks
This function executes the custom callbacks registered for a particular USER_ or
USERSERVICE_ 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_ or USERSERVICE_ exit.
• 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 window, accessed from the
Edit menu in My Navigator,
• Get the corresponding custom function pointer.
CUSTOM_execute_callbacks_from_library
• decision
Executes one of the following options:
– ALL_CUSTOMIZATIONS
– ONLY_CURRENT_CUSTOMIZATION
– NO_CUSTOMIZATIONS
• lib_name
Name of the customization context.
• ftn_name
Name of the USER_ or USERSERVICE_ exit.
• variables
The variables that need to be passed to the custom exit (a custom function
pointer).
Example
Figure 5-12 (using tceng_cust1 as the site) shows registering a custom handler
in a custom exit.
*decision = ALL_CUSTOMIZATIONS;
return rcode;
}
return ( ITK_ok );
}
2. To register the property methods, follow this sample registration in figure 5-13.
USER_prop_init_entry_t icsTypesMethods[] =
{
{ (char *)"WorkspaceObject", icsInitWorkspaceObjectProperties, NULL
}
};
}
else
{
// not yet registerd, add the method as a base method
// there is no method registerd
ifail = METHOD_register_method ( icsTypesMethods[i].type_name,
IMANTYPE_init_user_props_msg,
icsTypesMethods[i].user_method,
icsTypesMethods[i].user_args,
&methodld );
}
}
}
II ITK Modules
Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Mechatronics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
6 Core Functions
6 Core Functions
This chapter describes the modules that contain Teamcenter’s core functionality.
Core Classes
This section describes the object model in more detail. For most classes, the
description includes:
• The purpose of the class
– Methods to set and ask the attribute values are generally assumed
and not explicitly stated.
• Methods
create
Creates a new instance of the subclass. All subclasses must specialize this
method. A create method normally creates an instance of its class, initialize
its parent class, then initialize its own attributes. By convention, the create
and initialize methods take as arguments the values for the attributes for
which NULL values are not allowed. So normally it is possible to invoke the
create method followed immediately by a save method call.
delete
Deletes the object under the Teamcenter integrity rules. That is, you cannot
delete an object if it is being referenced or if it is loaded in another process.
save
Saves the object that has been manipulated in memory to the database.
lock/unlock
Obtains or releases a write lock in the database.
load/unload
Loads an object into memory from the database or removes an object from
memory. The unload method does not save. It would normally be used when
an algorithm or a user has no further need for the object and wants the
object to be free for modification or deletion by another process.
refresh
Reloads an object from the database. Obtains a write lock if requested.
extent
Returns the tags of all of the instances of a particular class.
POM_group
Categorizes or collects a set of users.
• Attributes
name
The name of the group which is unique among all groups.
privilege
A flag indicating whether this group has system administration privileges or
not.
• Methods
find
Returns the tag of the POM_group class or an instance of a subclass of the
POM_group class with a given name.
Group
Specializes the POM_group class to contain a description and a list of roles.
• Attributes
description
A text string to describe the group.
list_of_role
A list of roles that exist for this group.
POM_user
Represents a user of the POM.
• Attributes
user_id
The string used to uniquely identify a user to Teamcenter.
password
The user’s password for logging into the POM.
user_name
A common name used by people to identify a user.
status
A flag to indicate if the user has been deleted but still has references. This
flag can be set if the system administrator attempts to delete the user but
cannot completely do so because the user still owns some objects. The user
is still unable to login with the POM in this case.
def_acl
The default protection to be applied to all instances created by a user.
default_group
The group that the user is to be considered part of, unless another one is
specified. A user may belong to multiple groups.
• Methods
find
Finds a POM_user class instance or an instance of a subclass of the
POM_user class with the given user identification.
User
Specializes a POM_user class instance to understand the specifics of the Teamcenter
workspace and environment.
• Attributes
mailbox
A reference to the folder used as this user’s mailbox.
home_folder
A reference to the user’s home folder.
newstuff_folder
A reference to the user’s Newstuff folder.
person
A reference to the person that this user represents. More than one user may
reference the same person.
os_username
The character string that identifies the operating system user associated
with the user.
volume
A reference to the volume that Teamcenter uses by default as a location
for newly created or imported files.
• Methods
find_user_objects
Returns the tags of all of the objects owned by this user.
change_user_object_owner
Changes the owner of an object from one user to another user and group.
delete_user_objects
Deletes all of the objects owned by a given user.
POM_member
Associates a user with a group.
• Attributes
user
A reference to the user that is a member of the group.
group
A reference to the group that the user is a member of.
ga
A flag indicating whether the reference user is a group administrator for
this group or not.
• Methods
find
Finds a POM_member class instance or an instance of a subclass of
POM_member that associates a given user with a given group.
find
Finds all of the POM_member class instances in a given group.
find
Finds all of the POM_member class instances for a given user.
GroupMember
Enables users to play a role in a group, rather than just be a member of it.
• Attributes
role
A reference to the role object that the user is to play in this group.
• Methods
find
Finds all of the group members for a given role in a given group.
• Methods
initialize
All classes provide an initialize method, even if they do not have a public
create method. The initialize method is necessary for the create method
of a potential subclass to initialize the attributes of its parent.
archive/restore
Moves the bulk of an object’s data to a disk file. The bulk part is then deleted
from the Teamcenter database but the object remains and contains data
about where the archive information is.
backup
Copies the bulk of an object’s data out of Teamcenter.
• Specializations
– All of the POM_object methods are specialized by the AOM functions to not
only manipulate the object as a POM function would, but also to create,
manipulate, or delete other internal data structures that are specific to the
Teamcenter application.
When possible, you should always call AOM functions rather than
the equivalent POM function.
• Methods
describe
Returns a structure of useful information, such as object name, ID string
(name;revision), date created, date modified, and so on.
object_application
Returns the name of the application that creates and manipulates the
instances of the class, usually just Teamcenter. Some classes may specialize
this method. For example, the Dataset class’ method returns the name of
the tool that last modified them as the application.
revision_limit
Returns the number of revisions of a particular instance should be kept.
Most classes do not support revisioning; in that case, this equals 1.
getInfo
Returns the following basic information about a workspace object: name,
description, type, application, revision number, revision limit, owning user
name, owning group name, date created, date modified, date archived, date
of last backup, and date released.
setInfo
Sets new values for some of the attributes that were returned with getInfo.
freeInfo
Frees up the memory used in a getInfo operation.
find
Finds a workspace object of any subclass with a given name.
search
Finds all of the workspace objects of any subclass that matches the input
values for name, class name, owner, group, and various dates.
latest
Returns the latest revision of a given object. Since most classes do not
support revisioning, this method normally returns the input object. If the
class does support revisioning, then the newest revision is returned.
• Specializations
copy
Creates a new object just like the old one, optionally with a new name.
Folder
Provides a generic container of other objects in the workspace.
• Attributes
contents
A list of references to other workspace objects.
sort_order
A value indicating what order the user wants to see the folder contents in.
sort_criteria
The attribute on which to sort a folder’s contents.
• Methods
insert
Includes another workspace object in the folder’s list of references.
remove
Removes a reference to a workspace object in a folder’s list of references.
move
Moves an entry of a folder from one location in the list to another.
• Specializations
getInfo
In addition to the workspace object values, folders also return sort order, sort
criteria, and the number of entries in the folder.
Envelope
Provides a generic container of workspace objects that contains a list of receivers.
• Attributes
listOfReceivers
A list of users, groups, or distribution lists to send the envelope to.
sent_date
The date that the envelope was mailed.
sender
A reference to the user who sent the envelope.
• Methods
send
Places a reference to the envelope in the mailbox folder of each receiver.
• Specializations
– The name and description for an envelope have the specialized meanings of
subject and comments.
Item
Provides an identification for physical or conceptual entities about which an
organization maintains information and audit/control change. Items are the
fundamental objects used to manage information. Typical uses of items are parts,
documents and equipment. In engineering and product development environments,
parts are identified as items.
• Attributes
item_id
A unique character string which by the item is identified.
configuration_object_tag
The tag that points to the configuration object.
bom_view_tag
The tag that points to the BOM View.
uom_tag
The tag that points to the unit of measure.
• Specializations
create
Creates the item and the first item revision. This method also creates an
item master form for the item and the item revision. These forms have a
Master_form relation to the item and item revision.
delete
Deletes an item, its item master, and any relations to other objects. It also
deletes all item revisions of the item.
Item Revision
Reflects modifications to an item. Once an item revision has been released, a new
item revision can be created. The original item revisions are retained for historical
purposes. Customer sites define their own procedures to determine how and when
a new item revision should be created.
• Attributes
item_revision_id
A unique character string by which the item revision is identified.
items_tag
The tag that references the parent item.
structure_revision
The number of times the structure has been revised
• Specializations
find
Returns the item revision with a given item_revision_id and parent
item_id attributes.
copy
Creates a copy of the original item revision inside the same item.
create
Creates an item revision and an item master form. The item master form
has a Master_form relation to the item revision.
delete
Deletes the item revision, its item master, and any relations to other objects.
Dataset
Encapsulates the actual structure of a package of application data and associates
that package with a list of tools.
• Attributes
dataset_type
The tag of the DatasetType object that this dataset is a type of.
tool_used
The tag of the tool that created the particular dataset revision.
format_used
The format of the dataset.
user_class
A string attribute that enables you to further classify your datasets.
rev_chain_anchor
The tag of the revision anchor that associates the dataset with its previous
and subsequent revisions.
named_references
A list of references to objects that contain the actual application data. This is
presented through the interface as sets of three values:
– An object reference.
– A reference name.
– A reference type.
These are actually stored as three separate lists, ref_list, ref_names and
ref_types, which are kept in sync by Teamcenter.
• Methods
revise
Similar to the copy method, except the copy is considered a new revision of
the original dataset.
delete_all_revisions
Deletes all revisions of a dataset.
purge
Removes all old, non-referenced revisions except the latest.
• Specializations
revision_limit
A dataset object actually sets and asks the revision limit by using the keep
limit of its revision anchor.
copy
In addition to copying the dataset, this method also copies the revision
anchor. The new dataset becomes revision 1.
latest
Asks the revision anchor for the latest revision.
getInfo
Adds the dataset type name, tool name, site classification, and format to the
list of values returned by the getInfo method.
delete
Deletes the dataset and revision anchor if there are no other revisions and
the objects pointed to by the named references, they are the AE_PART_OF
type, and not referenced by another object or loaded in another session.
refresh
Refreshes the dataset and the revision anchor.
Tool
Represents an external application in Teamcenter. The tool must also contain
information about how to run the application and what kinds of input formats,
output formats, and parameters the application understands.
• Attributes
symbol_name
The command used to run the application.
site_classification
A text string that enables the user to classify tools.
shell_or_translator
A flag that indicates whether a tool is a normal application, a shell used to
communicate with an application, or a translator used to convert data from
one format to another.
encapsulator
The tag of the tool (shell) used to communicate between Teamcenter and
this tool.
input_formats
A list of formats this tool can understand as input.
output_formats
A list of formats that this tool can output.
variables
A list of names of input parameters that this tool can accept.
default_values
The default values of the above variables.
vendor_name
The name of the vendor that supplied the actual application.
version
The version of the application.
install_date
The date that the application was installed.
Form
Provides the customer with a collection of name/value pairs with enough information
to display a form window that can show and allow modification of the values.
• Attributes
form_file
The name of a compiled UIL file that contains the attribute names and
the layout of the form that Teamcenter uses for presenting it in the user
interface for display and modification.
data_file
The tag of the POM object that actually contains the name/value pairs. This
could be an ImanFile object or a POM class defined by the customer.
• Methods
ask_value
Returns the value of a particular attribute.
set_value
Sets an attribute value.
• Specializations
getInfo
Returns the workspace object values and the name of the form definition file.
delete, refresh, unload, and save
These methods act on the POM object or ImanFile object associated with
the form, as well as the form itself.
DistributionList
Contains the list of users, groups, and distribution lists that a particular type of
mail should go to.
• Attributes
listOfMembers
List of users, groups, and distribution lists.
Status
Represents an engineering task and the authorization process for that task.
• Methods
find
Finds a status with a given name.
Signoff
Associates an approval or authorization status with a group member.
• Attributes
group_member
The group member who is to decide to authorize or not.
decision
The decision. It must be YES, NO, or NO_DECISION.
decision_date
The date on which the decision was made.
comments
A string to contain any additional comments about the signoff. This is not
the same as the task comment.
Role
Describes a role that a user can play in a group.
• Attributes
role_name
The unique name of the role.
description
A description of the role.
• Methods
find
Finds a role with a given name.
Person
Represents an actual human being in the Teamcenter system. The person
profile can be customized by changing the selectedpersonwindowintl.uih and
selectedpersonwindowlocal.uih in the IMAN_LANGUAGE directory.
The following is the description of the person object model and how its attributes
are being mapped from the user interactive interface:
All of the attributes, form name, and pa1 through pa10 are optional
attributes that can store up to 32 characters.
• Attributes
first_name
First name of the person.
middle_name
Middle name of the person.
last_name
Last name of the person.
street_address
The person’s street address.
city
The city where the person lives.
state
The state where the person lives.
zipcode
The person’s zip or mail code.
organization
The name of the company’s organization that the person is in.
phone_number
The person’s phone number.
date_of_birth
The person’s birthday.
• Methods
find
Finds a person with the given first name, last name, middle name, and date
of birth.
ImanVolume
Represents a physical storage location for files in the operating system in the
Teamcenter database.
• Attributes
volume_name
The unique name of the volume.
unix_path_name
The path name of the volume in UNIX format.
wnt_path_name
The path name of the volume in Windows format.
node_name
The name of the machine that the volume (directory) is on.
users
The list of users and groups that have access to this volume.
protection_mode
Not currently used.
machine_type
The type of machine that the volume’s directory resides on.
• Methods
find_by_name
Finds the volume with the given name.
find_by_path
Finds the volume with the given pathname.
grant_access
Gives a user or group access to a volume.
revoke_access
Removes write access to a volume for a user.
check_access
Determines if a particular user has write access to a particular volume.
ImanFile
Represents an operating system file in the Teamcenter database.
• Attributes
file_name
The leaf name of the file in the Teamcenter volume.
original_file_name
The name the file is given if it is exported to the operating system by the
IMF_export_file function.
sd_path_name
The pathname to the operating system file. This is in a system-dependent
format.
translate
Indicates whether the file is stored in Teamcenter machine-translatable
format.
text_flag
Indicates whether the file is text or binary.
machine_type
Indicates what machine format the file is in.
volume_tag
The tag of the volume on which the operating system file resides.
status_flag
Indicates if the file is scheduled to be deleted.
time_last_modified
The time stamp on the file indicating when it was last changed by
Teamcenter.
released_version
Reserved for future use.
• Methods
open
Opens the operating system file associated with the ImanFile database
object.
close
Closes the operating system file associated with the ImanFile database
object.
read
Reads binary data or lines of text from a file.
write
Writes binary data or lines of text to a file.
import
Brings an existing operating system file under control of Teamcenter as an
ImanFile database object.
export
Copies an ImanFile database object into a specified operating system
directory, thus relinquishing Teamcenter control over the file.
DatasetType
Represents a named list of tools that can operate on a particular type of dataset.
• Attributes
datasettype_name
The unique name of the DatasetType instance.
description
A description of the type of data that this object represents.
parent_type
The tag of a DatasetType class that this instance is a kind of. Enables the
user to classify dataset types.
list_of_tools
The tags of all of the tools that can operate on datasets of this type.
action_list
The list of workspace actions (open, destroy, purge, and so on) for which
this type of dataset has specialized behavior. The default tool is run if the
particular action chosen is in this list. If not, the action has the default
Teamcenter behavior.
named_ref_list
The list of all of the possible named references that datasets of this type
may have.
• Methods
default_tool
Return the default tool for the dataset type. This is the first in the list.
find
Return the tag of the dataset type with a given name.
RevisionAnchor
Provides facilities for collecting an ordered set of related objects. Normally these
would be successive revisions of an object. It is used only for datasets.
• Attributes
revisions
A list of the revisions.
keep_limit
Indicates how many revisions to keep before attempting to delete the older
ones.
highest_rev
Indicates the highest revision ever achieved in the life of this revision anchor.
• Methods
latest
Returns the most recently created object in the set of revisions.
make_room
Removes a number of objects from the set of revisions.
purge
Removes all objects from the set of revisions, except the latest.
ItemMaster
Represents a form that has a Master_form relation with an item and item revision.
This class can be specialized at each site, and Teamcenter comes with some standard
attributes.
Form objects can store data in two different ways. In the system as delivered, item
master and item revision master data is stored in ImanFiles. The ItemMaster
class is provided if you prefer to store the data in POM. To store it in POM, you need
to modify the itemmaster.uil and itemversionmaster.uil files by changing the
POMClassName entries to ItemMaster.
• Attributes
project_id
The identification of the project under which the item was developed.
previous_item_id
The item that is being superseded by this one.
serial_number
A number assigned to the item by your organization.
item_comment
Comments made by the engineer.
user_data_1/2/3
Fields where the user can place data.
Unit of Measure
Represents the unit of measure for an item. Valid units of measure are defined for
an Teamcenter installation by the system administrator.
• Attributes
symbol
An 8-character symbol for the unit (for example, in for inches).
name
A full name for the unit.
• Methods
extent
Lists the units of measure valid for an installation.
create
ask/set name/symbol
ind by name/symbol
Product Structure Objects
Go to the Product Structure (PS) section Product Structure (PS) Module of this
manual.
File Relocation
When you create a dataset in Teamcenter, a file is created in the user’s 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.
To register an EPM action handler, use the EPM_register_action_handler
function. Input parameters should be action strings and function callbacks.
This function should be called in the user_gsshell.c file.
• action
3. Choose File→New Root Template. The New Root Template dialog window
is displayed.
4. Give the new root template a name and select another root template to base
this template on. Click OK.
6. Choose the task action where you want the handler to execute, then choose
the handler.
7. Choose the arguments needed for your handler and their values.
8. Choose the plus button to add the handler to the task action. When you are
done, close the Handlers dialog window.
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.
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
smp_cr_mv_fl.c
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.
The user-id variable is the Teamcenter user login name; password is the Teamcenter
user password; and group is the Teamcenter user group name.
Programmers can customize and extend the Teamcenter data model to more closely
agree with the enterprise data model. Three modules are used to accomplish this:
• Types
• Properties
• Methods
• FormType
FormType is a specialized ImanType used to define a type for the Teamcenter
Form class.
• DatasetType
DatasetType is a specialized ImanType used to define a type for the
Teamcenter dataset class.
Key Definitions
The following terms and concepts is widely used to describe types, properties, and
methods:
• Class
A class is the definition of an object implemented in the Teamcenter data model.
• Attribute
An attribute is a persistent piece of information that characterizes all objects
in the same class.
• Type
A type is the specialization of an Teamcenter class based on properties and
behavior.
• Primary Type
A primary type is a default ImanType that directly corresponds to each POM
class (in other words, the primary type name is the same as the POM class
name). Teamcenter automatically creates the primary type when a new POM
class is instantiated.
• Subtype
Subtypes are all types except the primary type that belong to the same POM
class. Subtypes inherit all the properties and behavior of the primary type.
You cannot create a subtype of a subtype in the same POM class.
• Property
A property is a piece of information that characterizes all objects of the same
type.
• Message
A message is a command that is passed to an object to execute some operation
(for example, save, copy, and delete).
• Method
A method is the execution of a message that is particular to that object type.
Relationship Diagram
Figure 6-1 shows the Teamcenter object model. It demonstrates the relationships
among objects, classes, and types. The figure also shows the relationships between
properties and attributes.
Types
Properties
Type data (for example, ID, Name, Description, and so on) is defined by a set of
properties. The messages used to control these properties can be customized and
extended using property methods.
Methods
Type behavior (for example, save, delete, create, and so on) is defined by a set of
messages that are passed to the type at runtime. These messages are implemented
using methods. Methods are C/C++ functions. Programmers can define new
methods for types or customize and extend existing methods by adding pre- and
postconditions to these existing methods.
Properties
Properties perform only a simple set of functions, namely asking and setting the
value of the attribute or relationship they represent. They can return a List of
Values (LOV) that is applicable for that property.
Properties are represented by two classes: ImanProperty and
PropertyDescriptor. The PropertyDescriptor class defines the property for the
type, while the ImanProperty class holds the value for a property instance.
In base Teamcenter, each type is specified by a set of properties that directly maps
to the attributes defined for a class. You can customize and extend these types by
adding new properties to new or existing types. These properties can represent
anything you wish to define for a type.
All properties belong to one of five classifications:
• Attribute-based
• Reference-based
• Relation-based
• Runtime
• Compound properties
Attribute-Based Properties
Attribute-based properties ask or set a simple value (for example, integer, string, and
date). The value is stored in the database as an attribute and mapped to the property.
Reference-Based Properties
Reference-based properties ask or set a reference to another object. The reference is
stored in the database as a Reference attribute and mapped to the property.
Relation-Based Properties
Relation-based properties ask or set a reference to secondary objects of an
ImanRelation type. The reference is stored in the database as a Relation type and
is derived from that ImanRelation type.
Compound Properties
Methods
Methods are user-definable functions that are associated with types and properties.
ITK methods allow Teamcenter sites to customize and extend the behavior of
Teamcenter objects and to incorporate enterprise business rules.
Methods are most often used to create subtypes in order to customize parent type
behavior. For example, instances of Class Item directly correspond to Type Item.
Methods can be used to define a subtype of item for a Teamcenter site to customize
the behavior of items at that site.
Inheritance
Actions
A method can be divided into four functions that are executed in the following
sequence:
1. Precondition
2. Preaction
3. Base action
4. Postaction
All methods must have a base action, the other actions are optional. Each registered
action function must return ITK_ok for processing to continue to the next action.
Otherwise an error is posted and an integer error code is returned.
Precondition is only intended to verify that no conditions exist that could prevent
the method from executing properly. Actual execution of the method should only
commence in the pre-action.
Careful planning of pre- and post-actions allows extension of base action behavior
without having to re-implement the base action.
Message Identification
Each message is uniquely identified by a text string. These strings are used to
register methods as type/message combinations. To maximize runtime performance
when executing methods, minimize repeated lookups of message IDs. Teamcenter
assigns runtime unique integers to each message (message ID) and passes them to
the METHOD_SETUP_MESSAGE macro. It caches the message IDs in a static int
where they are retrieved the next time the method is executed. This can be useful
when implementing custom message execution code.
Method Registration
int USER_init_module()
{
int ifail;
METHOD_id_t my_method;
return ITK_ok;
}
The following sample program listing shows the registered actions implemented
in the my_type.c file.
#include <my_type.h>
{
/* IMAN_save_msg is defined to pass the tag of the object as its only
** vararg.
*/
tag_t object_tag = va_arg(args, tag_t);
.
.
.
if (... everything ok to save...)
{
return ITK_ok;
}
else
{
return failure code;
}
}
{
/* IMAN_save_msg is defined to pass the tag of the object as its only
** vararg.
*/
tag_t object_tag = va_arg(args, tag_t);
Property Methods
Property methods are special methods that are attached to a property instead of a
type. Property method actions are identical to those described in the Actions section
above. However, there are slight differences in the way the following functionality is
implemented:
• Inheritance
Property methods inheritance is similar to Inheritance discussed earlier in this
topic, except that property methods can be inherited through multiple levels
of type hierarchy.
The primary type hierarchy directly corresponds to the class hierarchy. When a
new user-defined type is created, it becomes a new subtype of the primary type.
Consider the class and type hierarchy as shown in figure 6-2.
– The user-defined Part subtype is created for the NewItem primary type .
• Message ID
Property message ID is implemented as discussed earlier in this section, except
that property methods use a the METHOD_SETUP_PROP_MESSAGE macro
instead of METHOD_SETUP_MESSAGE.
• Registration
Property methods registration is subject to the same rule and limitations
discussed above. Because property methods are registered against a single
property, they have a separate registration call and function. Also, property
methods are not registered until the property is used for the first time.
int USER_register_properties()
{
int ifail = ITK_ok;
/*
* You can declare your function prototypes here or in another file
* #included by this one.
*/
extern int MYTYPE_prop_init_module();
/*
* This array is used to register methods which initialize properties
* on types. The message name is IMANTYPE_init_user_props_msg. No coding
* is necessary in this function. Just add an entry in this array to
* indicate the object type, the function which implements the property
* additions/modifications and the list of arguments.
*
* The array should be terminated with a NULL entry.
*/
USER_prop_init_entry_t user_types_methods[] =
{
{ "MyType" , MYTYPE_prop_init_module , NULL },
{ "" , 0 , NULL }
};
/*
* Do not edit this call. This call is not to be used elsewhere.
*/
ifail = IMANTYPE_register_properties(user_types_methods, n_types);
return ITK_ok;
}
The program does not hard code the type name. This is very important
to support the inheritance of the property onto subtypes. Always use the
IMANTYPE_ask_name function to get the type name from the type tag.
#include <prop.h>
return ifail;
}
After registering a property method to ask or set the value of a property, you must
write the actual property method function.
The sample program below shows how to write a property method to ask the value of
a runtime property. In this sample, the value is retrieved from storage, associated
with the property, and returned as-is. However, the value could have been retrieved
by calling any ITK function or by manipulating the value retrieved by the ITK
function using a suitable algorithm.
int MYTYPE_ask_newprop_value_function(METHOD_message_t *message, va_list args)
{
/* Extract property tag
*/
tag_t prop_tag = va_arg(args, tag_t);
char **value = va_arg(args, char**);
return ifail;
}
Canned Methods
Custom canned methods are included with the Teamcenter system and can be
configured using the Business Modeler application. Canned methods allow you, as
system administrator, to change the behavior of items, item revisions, and dataset
types without having to write custom code. The user interface for using canned
methods is within the Business Modeler application in the Action Rules tab. Once
the types are configured with canned methods, the configuration information is
stored and can then be easily distributed to your other sites, without having to redo
the configuration from Business Modeler.
You have to make changes to both the server side and client side.
Server-Side Changes
To add site canned methods in order for them to be configurable from the Business
Modeler application, use the METHOD_CM_add_method method on the server
side. Site canned methods need to be added at session startup using this method.
int METHOD_CM_add_method (type_name, msg_name, action_type, func_name,
user_data_template, is_mandatory_template, user_dataQuery_detail)
• 1 – during preaction
• 3 – during postaction.
func_name
Name of the canned method that appears in the Business Rules Application –
Action Rules Tree Node.
This argument must be unique for a given canned method.
user_data_template
Options required during canned method configuration and also during
registration. This must be a single string with each parameter separated in the
string by a double colon (::).
You cannot add, remove, or reorder the options in the user_data_template
argument unless you remove the existing configuration and repeat the
configuration for the associated canned method for all the affected types. This is
because the order and number of values stored in database is tightly tied to the
order of the values in the user_data_template argument.
is_mandatory_template
Details regarding whether a user_data_template parameter is mandatory or
optional. Use 1 for mandatory and 0 for optional. This must be a single string,
with each parameter separated in the string by a double colon (::).
user_dataQuery_detail
This can be NULL only if the user_data_template argument is NULL, or else this
should have a one-to-one mapping for the parameters in the user_data_template
argument. The saved query name should be used for parameters that need
to have a list box of values displayed in the rich client. A blank space (in
other words, " ") can be used for parameters that do not need any list box
values for display in the rich client. Along with the saved query name,
the attribute whose value needs to be displayed should be mentioned as
param1QueryName~attribute-name, where a tilda (~) must be the delimiter
between the saved query name and attribute name. The attribute-name is the
attribute of the query results whose value needs to be displayed in the list box.
2. SiteCannedMethod_2
A preaction on a saveAs message for all item revisions that takes no options for
the method.
3. SiteCannedMethod_3
A postaction on a delete message for a document item type that takes input on
the following method options: option_1, option_2 and option_3. Option_1
is mandatory and has values corresponding to the attr_1 attribute from the
execution result of the Query_1 query. Option_2 is not mandatory and does
not have any query information for its values. Option_3 is mandatory and has
values corresponding to the attr_3 attribute from the execution result of the
Query_3 query.
You can set up site canned methods on the server side by following these steps:
1. Register the site canned methods:
#include <typecannedmethod.h>
#include <iman_arguments.h>
……….
int inx = 0;
{“SiteCannedMethod_1”, (METHOD_function_t)siteCannedMethodFunc_1_ptr},
{“SiteCannedMethod_2”, (METHOD_function_t)siteCannedMethodFunc_2_ptr},
{“SiteCannedMethod_3”, (METHOD_function_t)siteCannedMethodFunc_3_ptr}
}
For an example of how to implement site canned methods, see Canned Methods
Example, later in this section.
siteFuncNamePtrMapping[inx].func_ptr);
ifail = METHOD_CM_add_method(
siteCannedMethods[inx].classOrObjectType,
siteCannedMethods[inx].msgName,
siteCannedMethods[inx].actionType,
siteCannedMethods[inx].funcName,
siteCannedMethods[inx].userDataTemplate,
siteCannedMethods[inx].isMandatoryTemplate,
siteCannedMethods[inx].userSavedQueryDetail );
Figure 6-3 shows a detailed example of how to construct your ITK program to add
canned methods.
#include <stdio.h>
#include <grmtype.h>
#include <iman.h>
#include <iman_arguments.h>
#include <iman_msg.h>
#include <item_msg.h>
#include <method.h>
#include <typecannedmethod.h>
#include <wso_msg.h>
#include <typecannedmethod_errors.h>
ec = POM_instance_exists(cannedMethod, &instance_exists);
if (ec != ITK_ok) fprintf(stdout, "\tPOM_instance_exists failed with
%d\n", ec);
if (instance_exists == FALSE)
{
fprintf(stdout, "\tCanned Method Tag is Not Valid\n", ec);
ec = METHOD_CM_invalid_method_tag;
}
else ec = ITK_ok;
return ec;
}
tag_t
*new_item = NULL,
*new_rev = NULL,
cannedMethod = NULLTAG;
char
method_name[METHOD_CM_MAX_METHOD_NAME_LEN + 1] = "",
type_name_from_method[WSO_name_size_c +1] = "",
msg_name[METHOD_CM_MAX_MSG_NAME_LEN + 1] = "",
***option_values = NULL,
*item_id = NULL,
*item_name = NULL,
*type_name_from_msg = NULL,
*rev_id = NULL;
fprintf(stdout, "myCMwithLOV...\n");
/********************************************************************
* This section demonstrates how to get information from the method
********************************************************************/
IMAN_init_argument_list(msg->user_args);
cannedMethod = IMAN_next_int_argument(msg->user_args);
ec = verifyCannedMethodTagIsValid(cannedMethod);
if (ec != ITK_ok) return ec;
/********************************************************************
* This section demonstrates how to get information from the message
********************************************************************/
item_id = va_arg(args, char *),
item_name = va_arg(args, char*),
type_name_from_msg = va_arg(args, char*),
rev_id = va_arg(args, char*);
new_item = va_arg(args, tag_t *),
new_rev = va_arg(args, tag_t *),
/********************************************************************
* Add custom post action code here
********************************************************************/
return ec;
}
/****************************************************************************
* registerMyCMwithLOV
*
* This function registers a canned method that uses two List of Values
* The LOVs are based on two saved queries, myCMobjectTypes and
* myCMrelationTypes, both having the attribute type_name as search critrea.
*
* Add the following lines to com\ugsolutions\iman\businessrules\common\
* common_user.properties file:
* myCMwithLOV.DESC=Description for myCMwithLOV
* myCMwithLOV.objectType.LABEL=Select Object Type?
* myCMwithLOV.relationType.LABEL=Select Relation Type?
****************************************************************************/
extern int registerMyCannedMethodwithLOV( void )
{
int
ec = ITK_ok;
fprintf(stdout, "registerMyCannedMethodwithLOV...\n");
ec = METHOD_CM_register_function("myCMwithLOV",
(METHOD_function_t) myCMwithLOV);
if (ec == ITK_ok) fprintf(stdout,
"\tMETHOD_CM_register_function successful!\n");
else
{
fprintf(stdout, "\tMETHOD_CM_register_function failed with %d!\n", ec);
return ec;
}
ec = METHOD_CM_add_method("Item", ITEM_create_msg,
METHOD_CM_Post_Action_type,
"myCMwithLOV", "objectType::relationType", "Y::Y",
"myCMobjectTypes~type_name::myCMrelationTypes~type_name");
return ec;
}
Client-Side Modifications
To register the canned method on the rich client, you have to modify either the
common_user.properties file or the common_locale.properties file in the
com.ugsolutions.iman.businessrules.common directory. The entries are:
• func_name.DESC=description
This description of the canned method displays in the Business Modeler
application. The tooltip for the tree node in the Business Modeler application is
the same. This entry is required
• func_name.userData.LABEL=question
This is a question you can place in the Business Modeler application to prompt
the user to enter a value. This entry is required only if the canned method has
data in the user_data_template argument.
For example, for a canned method to create objects when an item or item revision
is created, the method needs to know which objects to create and what relation
to attach to them. For this method, the user_data_template argument would
be objectType::RelationType. Corresponding to the user_data_template
argument, there needs to be entry in the common_user.properties or
common_locale.properties file as shown below:
createObjects.objectType.LABEL=Object of which type needs to be created?
createObjects.RelationType.LABEL=What relation should the above object be
attached with to the Parent Object?
Figure 6-4 displays the various texts in the Business Modeler application.
Based on the func_name (as shown in this example, createObjects) the other
entries, such as createObjects.DESC, createObject.objectType.LABEL, and
createObjects.RelationType.LABEL are obtained from the properties file. The
information obtained from the server is:
• func_name (here createObjects)
• Mandatory details for each of the parameters. If a field is mandatory, the input
field is displayed with a red triangle in the top right corner.
• Saved query names for each of the parameters. If a field needs to have the values
from a saved query, they are obtained based on the user_dataQuery_detail
information.
Figure 6-4 shows the how the properties file entries and the
METHOD_CM_add_method method arguments appear in the
Business Modeler application.
1 func_name = createObjects.
2 createObjects.DESC = This method will create specified objects
and attach them with specified relation to the Type for which this
canned method is configured.
3 createObjects.objectType.LABEL = Object Type To Create.
4 createObjects.RelationType.LABEL = Relation To Attach With.
5 user_data_template = objectType::RelationType.
• Adding types
You can add new types using the install_types utility or the IMANTYPE ITK
functions. For more information about the install_types utility, see the Utilities
Reference manual. For more information about the IMANTYPE ITK functions,
see the Integration Toolkit Function Reference manual.
• Adding properties
You can add new properties to a type by declaring the function prototype
and inserting the name of the type and the function name into the
user_types_methods array definition inside the USER_register_properties
function in the user_init.c file. For more information, see Registering a Property
init_module Function, earlier in this chapter.
Teamcenter only allows one level of subtypes to be added to each POM class. In
other words, you cannot create a subtype of an existing subtype in the same POM
class. Therefore, if you need additional subtypes, they must be added to a new POM
class or subclass. There is no limitation to the number and levels of subclasses that
can be added to a POM class.
The best way to specialize an existing Teamcenter object is to add a new type
rather than creating a new subclass. This is because subtypes inherit all the
properties and behavior of the super-type (in other words, primary type).
Also, adding a new subclass by extending the POM schema is a permanent
change. A type can be removed at a later date when it is no longer needed.
When creating a type for the Item class, corresponding types must be created
for the ItemRevision, ItemMaster, and ItemRevisionMaster classes. The
IMAN_BIN/install_types utility automatically creates these parallel types when a
new type is added to any one of the four classes. However, if one of the four parallel
types is deleted, the other three are not automatically deleted.
Teamcenter does not allow subclasses of the Item or ItemRevision POM
classes. If you try to add a subclass to them, you may see unpredictable
behavior and lose data. Therefore, use types to specialize these classes.
When creating a subclass of the Folder class, use the Schema Browser to create the
new subclass. Because there is no user interface for creating instances of Folder
subclasses, you must write some user interface extensions to instantiate any new
Folder subclasses.
Although the Dataset POM class can be subclassed, it is not advisable. Instead, use
a dataset type to specialize this class. Additionally, it is possible to extend a dataset
type by adding a form as a named reference. For more information about creating
and managing dataset types and named references, see Type Help.
Although the Form POM class can be subclassed, it is not advisable. Instead, use
a form type to specialize this class. For additional information about creating and
managing form types, see Type Help.
• install_types utility
For example:
$IMAN_BIN/install_types -f=add -c=ImanRelation/
-t=CUSTOM_model
2. Define two text strings for this new relation type. One string is singular and is
used to display the relation type name in the user interface (for example, in
the Workspace Relation column). The other string is plural and is used when
displaying pseudo-folders.
3. Define the relation type text strings by adding new entries to iman_text.uil
according to the following format:
gk_relation-name_att
gk_relation-name_pf
For example:
gk_CUSTOM_model_att : exported "Model";
gk_CUSTOM_model_pf : exported "Models";
4. Compile the iman_text.uil file and copy the resulting the iman_text.uid file to
IMAN_APP_UID_DIR or IMAN_USER_UID_DIR as appropriate.
5. Define a display name for the property that is mapped onto this relation by
adding the following to the user_property_names.uih file:
CUSTOM_model : exported "Model";
7. To make this new relation type accessible from the Item Display Options dialog
window, add a relation-name_relation_primary preference entry to the site
preference stored in the database, listing each type of item and item revision you
want to be able to show the relation under. For example:
CUSTOM_model_relation_primary=
Item
ItemRevision
Document
DocumentRevision
You can also attach relations to objects other than items and item
revisions, but steps 5 and 7 would not apply in such a case, as you
cannot display such relationships in the workspace.
You can add a persistent property to an existing type by adding the corresponding
attribute to an existing class or to a new subclass. The following shows various ways
to add a new persistent property, property2, to the database.
3. Insert code into the property init module function to customize the behavior of
property2.
Because of the limitations that exist for adding attributes to existing Teamcenter
classes, another technique for adding a persistent property to a type is to create a
new subclass with the desired attributes. These attributes can then be mapped to a
new type. Figure 6-6 shows an example of adding an attribute to a new subclass.
2. Add the new SubExampleA primary type with the install_types utility or the
IMANTYPE ITK functions.
3. The SubExampleA type inherits all of the properties of the ExampleA primary
type and automatically has a property that corresponds (in other words, has the
same name as) to attribute2.
Steps 4 and 5 are only required if you are customizing the default
property behavior.
5. Insert code into the property init module function to customize the behavior of
property2.
Adding a relation between two classes (in other words, between a primary class and
a secondary class) is a technique that allows all the attributes of both classes to be
displayed as properties associated with the primary class. There are two approaches
that can be used for adding a relation between two classes:
• Teamcenter preference settings
• ITK
Figure 6-7 shows how property2 can be added to the ExampleA type from the
ExampleB class using the RelationAB relation.
4. Insert code into the property init module function to customize the behavior of
property2.
3. Insert code into the property init module function to add the property2
relation property.
Step 4 is only required if you are customizing the default property
behavior.
4. Insert code into the property init module function to customize the behavior of
property2.
2. Insert code into the property init module function to add runtime property2.
3. Insert code into the property init module function to customize the
behavior of property2. This must include registering a method against the
PROP_ask_value_type_msg function. This function contains the code for
deriving the value of this runtime property.
When you add a runtime property, the locking, unlocking, refreshing
and saving of the referenced object must be performed by the new
code. This is especially important when writing a method for the
PROP_set_value_type_msg function. Your code must lock the object, set
the value, save, and unlock the object entirely within the method.
You can add a compound property by defining a compound property rule through the
Compound Property rule module of the Business Modeler application. For further
details about creating a compound property rule, see Business Modeler Help.
UGS recommends that you use the Compound Property rules functionality when
you want a property to be displayed from an object (display object) as if it were the
object’s own property, though it is actually defined and resides on another object (the
source object), where the display and the source objects are connected through one
or more reference/relation properties.
There are two basic approaches that can be used to customize behavior of a type:
• Customize overall behavior (for example, create, save, delete)
The overall behavior of a type (for example, create, save, and delete) is defined by
a set of messages that are passed to the type at runtime. These messages are
implemented using methods. New methods can be defined for a type (base action)
or existing methods can be customized and extended by adding a precondition,
preaction, or postaction.
It is also possible to change the ask, set, and initialize behavior of both existing and
newly created properties. This is accomplished with the following ITK messages:
• PROP_UIF_ask_value_msg
• PROP_UIF_set_value_msg
• PROP_init_value_msg
• PROP_ask_value_type_msg
• PROP_ask_value_types_msg
• PROP_ask_value_type_at_msg
• PROP_set_value_type_msg
• PROP_set_value_types_msg
• PROP_set_value_type_at_msg
• PROP_is_modifiable_msg
• Integer (int)
• Logical (logical)
If you want to customize the master suffix (for example, change it from Master to
_Master), follow these steps:
1. Go to the IMAN_ROOT/lang/textserver/language directory and open the
iman_text.xml file in a text editor.
3. Change the key entry to your custom master suffix (for example, change it from
Master to _Master).
7. Expand the Form Type and click the Item Master type.
8. In New subtype name, enter the new Form type name that reflects the new
suffix. It must be in the form Itemnew-suffix (for example, Item_Master).
9. Click Create.
11. Repeat steps 8–9 for ItemRevision Master. It must be in the form
ItemRevisionnew-suffix (for example, ItemRevision_Master).
When you restart the rich client, the new master suffix takes effect.
• Method arguments
• Messages
• Value caching
• Display names
• Hiding properties
• Workspace columns
Memory Allocation
If string values are to be passed from one function to another, the memory allocated
to these string values must be persistent. Therefore, the following memory allocation
ITK calls must be made:
• MEM_alloc_persistent
• MEM_string_copy_persistent
These functions ensure retention of memory until the MEM_free function is called.
Method Arguments
Messages
The following sections provide hints, guidelines, and cautions about specific message
functions.
PROP_init_value_msg
PROP_ask_value_type_msg
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 window or sets a value in the workspace, PSE, or
with ITK. The PROP_assign_value_type function can be used.
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.
Value Caching
Display Names
Each Teamcenter property can be displayed in the user interface using the actual
(in other words, programming) property name or another more descriptive display
name. In most cases, the display name is more useful. Either of the following
techniques can be used to define property display names:
• Call the PROPDESC_set_display_name function in the property initialization
module function registered for the type on which this property exits.
If the name is set using the first technique, it appears in the Attributes
dialog window and is returned by the PROPDESC_ask_display_name and
AOM_UIF_ask_name functions.
If the name is set using the second technique, it is also a possible candidate for a
workspace column.
Hiding Properties
There are two techniques for hiding a property from the end user:
• Comment out the display name of the property as follows:
In the IMAN_ROOT/lang/textserver/language/user_property_names.xml
file, add the following:
<key id="">system_prop_name</key>
The first option is preferable if you only want to hide unneeded properties from
the end user.
Ensure that the property name does not already exist in the
system_property_names.xml file.
Workspace Columns
WSShownColumnWidthsPref=
20
32
32
7 System Administrator
7 System Administrator
This chapter describes the modules that contain system administration functionality.
List of Values
Use the List of Values (LOV) functions to define lists of values and to associate
them with attributes and properties. Associations can be stored in the database
(persistent) or independently associated for each Teamcenter session (runtime).
There are three types of LOV:
1. Properties based on type
3. Runtime properties
LOV is defined as a class in Teamcenter. Programmers can create, modify, and delete
LOVs using either ITK or the List of Values application in Teamcenter. This allows
you to view LOVs by entering ? in any attribute field.
Runtime Properties
LOVs based on runtime properties are created and associated during each
Teamcenter session and are not persistent (in other words, not stored in the
database). For example, an attribute could have separate LOVs defined for each
state of a runtime property (for example, is_late: YES or NO).
• Range of Values
LOV defines a range (upper and lower limits) of acceptable values. Other values
are not allowed.
• Suggested Value
LOV provides user with suggested values. Other values are allowed.
LOVs can contain integers, floating-point decimals, strings, dates, and tags. You can
register the handlers used to create LOV contents.
Access Manager
Custom Privileges
To create a new custom privilege, you must perform the following tasks:
• Define the new privilege in the am_text.xml file.
• Add the new privilege to the database using the install utility.
There are two attributes of a custom privilege that you must manually define in
the am_text.xml file:
• Privilege name
• Privilege token
The privilege name is the unique identifier that Teamcenter uses to store privileges
in the database; the token is the single-letter mnemonic for that privilege (for
example, R is the token for the default read privilege).
Figure 7-1 is a partial listing of the am_text.xml file:
NAME is the name and T is the single-letter token you define for
this new custom privilege.
2. Run the install utility with the -priv argument by entering the following:
install -priv NAME infodba password dba
password is the infodba password and NAME is the new name for this
custom privilege you defined in step 1.
Audit Manager
Business Modeler
2. Add a user exit macro entry in the appropriate (type or property) BMF message
mapping block defined in the bmfuserexithelper.cxx file (found in the
src/bmf/code directory):
ADD_BMF_USER_EXIT_MSG(typeName, message, extensionName,
functionPointer)
ADD_BMF_USER_EXIT_PROP_MSG(typeName, message, propertyName,
extensionName, functionPointer)
• For type user exit messages that support the methods framework:
For example, if you introduce a new type user exit message, such as
ITEM_myexit_msg on item types, then update the following list in the
bmfuserexithelper.cxx file:
BEGIN_BMF_MSG_MAP(BMFUserExitHelper,"BMFUserExitHelper"):
ADD_BMF_USER_EXIT_MSG("ImanQuery", QRY_execute_msg,
"BMF_USER_query_execute", 0)
ADD_BMF_USER_EXIT_MSG("Appearance",
APPR_update_enditem_search_results_msg,
"BMF_USER_appr_update_end_item_search_results", 0)
ADD_BMF_USER_EXIT_MSG("Item", ITEM_create_msg,
"BMF_USER_create_item", 0)
ADD_BMF_USER_EXIT_MSG("Item", ITEM_create_post_msg,
"BMF_USER_item_created", 0)
ADD_BMF_USER_EXIT_MSG("Item", ITEM_myexit_msg,
"BMF_USER_myexit", 0)
END_BMF_MESSAGE_MAP()
• For property user exit messages that support the methods framework:
For example, if you introduce a new property user exit message to get
a custom user description, such as ITEM_get_desc_msg on a property
“object_desc” on item types, then update the following list in the
bmfuserexithelper.cxx file:
BEGIN_BMF_PROP_MSG_MAP(BMFUserExitHelper,"BMFUserExitHelper"):
ADD_BMF_USER_EXIT_PROP_MSG("Item", ITEM_check_above_erct_msg,
"user_data1", "", 0)
ADD_BMF_USER_EXIT_PROP_MSG("Item", ITEM_ask_display_revisions_msg,
"configuration_object_tag", "", 0)
ADD_BMF_USER_EXIT_PROP_MSG("Item", ITEM_assign_new_id_msg, "item_id",
"", 0)
ADD_BMF_USER_EXIT_PROP_MSG("Item", ITEM_get_desc_msg,"object_desc",
"", 0)
END_BMF_PROP_MESSAGE_MAP()
3. In the user exit itself, add the following macro before executing any
other statements. This macro is defined in the bmf.h file, located in the
src/itk/code directory. See examples in the user_part_no.c file, located in the
src/user_exits/code directory. The variable argument list is dependent on the
specific parameters that any user exit requires.
BMF_EXECUTE_USER_EXIT_EXTENSIONS(typeName, propName, message, args...);
This section describes what is involved in coding a custom extension for use within
the Business Modeler Framework (BMF). The example referenced here is used in the
implementation illustration in the following section. This custom extension initiates
a workflow process on an item revision (after it is created) when creating an item.
This is custom code developed using standard ITK development practices.
#ifndef BMF_SAMPLE_C_2
#define BMF_SAMPLE_C_2
#include "bmf_extension_utils.h"
#include <epm.h>
#include <bmf.h>
#include <libuserext_exports.h>
#include <libuserext_undef.h>
#endif // BMF_SAMPLE_C_2
• #include bmf.h
Contains the structure definition (BMF_extension_arguments_t) needed
for processing user parameter data. This is processed as an array of these
structures by the developer.
typedef struct BMF_extension_arguments_s
{
char paramName[BMF_EXTENSION_ARGNAME_size_c + 1];
union val_union
{
int int_value;
double double_value;
char str_value[BMF_EXTENSION_STRGVAL_size_c + 1];
}arg_val;
} BMF_extension_arguments_t;
paramName
Contains the value of the Name field entered by the administrator in the
Parameter Details dialog window when defining the extension through the
Business Modeler application (see the example in Step 3: Implement the C
Custom Extension). In the example, there are two: Release Process and
Company ID.
val_union
Contains the actual value defined for the specified paramName when the
administrator assigns the extension to an entry point in the Argument Panel
for extension on the Assign Extension tab (made up of only one of the three
value definitions at one time based on the type of value). In the example,
Release Process is a mandatory String, and Company ID is an optional
Integer. A mandatory value is always present. An optional value may or
may not be present.
• #include libuserext_exports.h
Contains definitions needed for processing.
• #include libuserext_undef.h
Contains the symbol definition processing required for the user extension API.
• Any additional #include lines that need to be defined for the custom extension
based on functionality. In the sample, the epm.h file is needed because of the
workflow processing functionality it is using.
• USER_EXT_DLL_API
extern USER_EXT_DLL_API custom-extension-function
#include "bmf_extension_workflow_sample.h"
int getArgByName(BMF_extension_arguments_t* p,
int arg_cnt,
const char* paramName)
{
int i;
for (i =0; i < arg_cnt; i++)
{
if (iman_strcmp(paramName, p[i].paramName) == 0)
{
return i;
}
}
return -1;
}
char * item_id;
char * item_name;
char * type_name;
char * rev_id;
tag_t * new_item;
tag_t * new_rev;
/********************/
/* Initialization */
/********************/
item_tag = *new_item;
rev_tag = *new_rev;
MEM_free(input_args);
/**************/
/* ITK code */
/**************/
If (relproc != NULL)
{
if (rev_tag != NULLTAG)
{
sprintf( job_name, "%s/%s-%d Job",
item_id, rev_id, companyid );
sprintf( job_desc,
"Auto initiate job for item/rev (%s/%s-%d)",
item_id, rev_id, companyid );
return ifail;
} /* end of function - bmf_extension_workflow_sample */
• Any source code functions that need to be written to support the custom
extension based functionality. In the sample, there are two functions:
int getArgByName(
BMF_extension_arguments_t* p,
int arg_cnt,
const char* paramName)
Retrieve the message parameters for the current operation using va_arg.
In this example, the current operation is ITEM_create_msg. So there are
four character string (pointers) and two tag_t pointers to retrieve. This data
represents item ID, item name, type name, revision ID, new item, and new
revision, respectively.
Retrieve the custom extension parameters from the user parameters of the
message using the BMF_get_user_params function. In this example, the
custom extension is bmf_extension_workflow_sample. So there is one
mandatory character string value and one optional integer value to retrieve.
This data represents Release Process and Company ID, respectively.
• Process each of the individual extension parameters that have been retrieved
into the array of BMF_extension_arguments_t structures.
Call the getArgByName local function to retrieve the appropriate value for
each data element and assign it to the appropriate variable.
The source code needs to be able to handle optional parameters that were not
assigned on a particular extension point.
• Now all of the data from the message and from the custom extension should be
available to you. Write the rest of the ITK functionality to accomplish the goal.
• The message data and custom extension user data are independent of each
other so it does not matter which is processed first. However, they should be
processed together as a set.
• You are expected to know the data that exists for the message. This includes
data types and the retrieval order so this data can be processed properly using
va_arg.
• You are expected to know the user data that exists for the custom extension. This
includes data types and whether each data element is mandatory or optional
so that this data can be processed properly after the BMF_get_user_params
function is used to retrieve this data.
– Use the compile scripts (discussed below) and specify multiple targets to
be compiled.
– Execute the link script once to produce the library containing these
extensions.
Compile and link the C custom code into a library. The directory path to this
library file is important and is used in a site preference value (described in Step 3:
Implement the C Custom Extension). This example describes a Windows build but
the process is similar for UNIX or Linux.
1. Start the Teamcenter environment console.
If there are errors, they show up between the create and link lines.
This example illustrates how to set up a custom extension. It involves defining the
extension to the system and assigning the extension points to use this extension.
The implementation of the workflow custom extension (the sample developed in
the previous steps) initiates a workflow process on an item revision when creating
an item.
1. Launch the rich client and log into the Business Modeler with a user who has
the dba role.
2. Choose Edit→Options.
3. Click Search and enter BMF in Search on keywords. Click the Search button.
5. Set it to the full directory path where the extension files are located and choose
Modify.
Multiple path definitions are allowed and you can define both Windows and
UNIX/Linux paths at the same time. The application only loads those that match
the current server platform. This preference needs to be set so that the application
knows where to look for custom extensions. Once set, close the rich client and
start it again to load the new site preference values. For more information, see
the Configuration Guide.
Step 4: Define the Extension Using the Business Modeler User Interface
1. In the Business Modeler, click the Extension Rules tab. The Define Extensions
subtab is displayed.
5. In Parameter Set, select Multiple since there are two input parameters
(Release Process and Company ID).
• Click Apply.
• Click Apply.
• Click Apply.
3. Click the Add button on the top right to add an empty row in the Extension
Name list.
4. Double-click the Extension Name field in the table row and select
bmf_extension_workflow_sample.
You see a TCM workflow process attached to the item revision when the item is
created.
Classes
Extension
This class stores information about the method information that is executed in an
operation. The attributes in this class are:
name
The name of the extension. The format is namespace::class::function-name
library_name
The library or JAR file name without extension.
lang_type
An enumerated value defined in the bmf.h file.
argdefs
The arguments this extension accepts.
validity
An array of strings that stores the ExtensionPoint classes that would be able
to configure this extension
BMOperation
This class stores information about the operations that can be performed on types or
properties. The attributes in this class are:
operation_name
The name of the operation. It is the message name on type or property.
extensionpoints
The ordered list of ExtensionPoint classes associated with this operation.
ExtensionPoint
This class stores information about the hookup point for executing methods. Four
extension points are supported: precondition, preaction, base action (not exposed to
user interface) and postaction. The attributes in this class are:
name
The name of the extension point.
is_overrideable
This value is false for base action. For the other points, this is true.
single_extension_only
This is true for base action
extpnt_type
This is an enumerator with four values.
ext_descriptors
The ordered list of configured extensions with parameters.
ExtensionDescriptor
TypeBMOperation
This class stores information about operations specific to types. The attributes in
this class are:
type_name
The name of the type on which the operation or messages are defined.
PropertyBMOperation
This class stores information about operations specific to properties. The attributes
in this class are:
type_name
The name of the type.
prop_name
The name of the property on which the operation is defined.
BusinessRuleDescriptor
This class stores information about versions of a business rule. It is used for tracking
versions of operation. The attributes in this class are:
version
A string value representing a version. This is only used internally.
This chapter describes the modules that contain product structure management
functionality.
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, there are certain procedures that you must follow.
Finding 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.
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
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 BOMView revision (the parent) to the items which 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 BOM by referring to occurrence sequencing. For detailed information about
the BOM and product structure (PS) functions, see the Integration Toolkit Function
Reference manual.
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).
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 sequence 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.
/* An example program to show a list of a bill of materials using the BOM module
@<DEL>*/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <unidefs.h>
#include <mem.h>
#include <iman.h>
#include <item.h>
#include <bom.h>
#include <cfm.h>
#include <ps_errors.h>
/*-------------------------------------------------------------------------------*/
/* This program lists the bill under some given item (configuring it by latest+working).
It then doubles all the sequence numbers and re-lists it by descending sequence 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.
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;
double_sequence_nos (top_line);
/* we will not use
ifail = BOM_save_window (window);
because that would modify the database
*/
print_average (top_line);
ITK_exit_module(true);
return 0;
}
/*-------------------------------------------------------------------------------*/
depth ++;
ifail = BOM_line_ask_attribute_string (line, name_attribute, &name);
CHECK_FAIL;
/* note that I know name is always defined, but sometimes sequence number is unset.
If that happens it returns NULL, not an error.
*/
ifail = BOM_line_ask_attribute_string (line, seqno_attribute, &sequence_no);
CHECK_FAIL;
MEM_free (children);
MEM_free (name);
MEM_free (sequence_no);
}
/*-------------------------------------------------------------------------------*/
int ifail;
char *sequence_no;
int i, n;
tag_t *children;
MEM_free (children);
}
/*-------------------------------------------------------------------------------*/
/*-------------------------------------------------------------------------------*/
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;
MEM_free (children);
}
/*-------------------------------------------------------------------------------*/
/*-------------------------------------------------------------------------------*/
/*-------------------------------------------------------------------------------*/
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. Refer to Occurrence Sequencing for the BOM and
Product Structures in the Integration Toolkit Function Reference manual.
• 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
Table 8-1 lists each variant expression operator, the type of left and right operands
allowed in that expression, and a brief description.
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.
Runtime 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 runtime. 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. Figure 8-2 shows an example of listing and setting option values:
#include <string.h>
#include <unidefs.h>
#include <iman.h>
#include <bom.h>
void panic();
void error(const char* message);
The BOM variant rule is a runtime 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 window’s current BOM variant rule can be obtained by a call to the
BOM_window_ask_variant_rule function.
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"
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.
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.
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 structure’s BOM line, using the
BOM_line_set_stop function. The stop flag can be cleared using the
BOM_line_clear_stop function. In PSE-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:
• Compare descriptor
Compare Descriptor
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.
Figure 8-3 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 */
/* All occurrence-based 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;
}
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);
CMP_create_prop_element(new_desc,
CMP_aggregate_element,
CMP_cache_sync,
NULL,
false,
bomline_type,
"bl_item",
"bl_item_item_id",
&new_element);
CMP_create_prop_element(new_desc,
CMP_aggregate_element,
compareCacheSync,
"k_compare_qty",
false,
bomline_type,
"bl_quantity",
NULL,
&new_element);
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;
}
• Auto Pack
In the call to the BOM_compare_define_mode function, the fifth argument
defines whether multi-level 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 multi-level compares where the primary compare elements match the
pack rule attributes. By default, the BOM line pack attributes are item ID and
sequence number. These are the primary attributes for the standard multi-level
compare as currently supported by the PSE compare dialog window.
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
the BOM line (for example, Qty 2->3 or Rev A->B). If you are performing an
occurrence-based compare, you might have two occurrences behind a packed
BOM line. One occurrence might have a change (for example, Qty 2->3). The
other occurrence might not have any change. In this situation, what should
compare put in the Changes property of the BOMLine? Should it say Qty 2->3?
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, UGS 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
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 non-property 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.
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++)
{
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);
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 described
earlier. 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 non-property data to be used. You can also define as many display
properties as you want.
CMP_create_prop_element(new_desc,
CMP_display_element,
CMP_cache_sync,
NULL,
false,
bomline_type,
"bl_item_object_name",
NULL,
&new_element);
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).
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, sequence 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.
• BOM_compare_stop_if_diff
• BOM_compare_dont_report_adds
• 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 PSE (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 sequence 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 sequence numbers are
strings and not integers, a string compare is performed and alphabetically 100 comes
before 20. To get around this, mark the sequence 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.
By default, report output is generated with the columns in the same order as the
elements were defined in. In the previous section we defined the Sequence Number
element ahead of the Item Id element to force the object output order to match the
PSE 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 PSE column display
order where you expect to have the item defined in the leftmost column, followed by
the sequence number. You can suppress the display of the sequence number element
and define a display element against the sequence 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 figure 8-6.
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 element’s 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 element’s cache when the supplied object is added
to the given side of the compare set.
• 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 non-property 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, UGS highly recommends caching.
For an example of a non-property 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 (PSE’s default quantity, in other words, one unit).
{
tag_t compare;
BOM_compare_create(&compare);
BOM_compare_execute(compare,
bomline1, bomline2,
"example mode",
0 /* No output - we’re going to do it ourselves */ );
BOM_compare_visit_engine(compare,
enter_engine,
leave_engine,
visit_set,
NULL /* User data pointer */ );
}
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);
SM_free(uif_name);
SM_free(lvalue);
SM_free(rvalue);
}
SM_free(elements);
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 PSE. 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 PSE 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 Product Structure Editor Help, 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 sequence
number, the primary keys, and where both sides of the compare has correlate
subsets, they are compared for quantity and revisions, the aggregate keys.
User Exits
BOM Compare can call a number of user exit functions for both ITK- and PSE
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 PSE 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.
The following BOM line string property is set to contain the changes relating to
the particular BOM line:
bl_compare_change
If no differences are found for a particular BOM line, these properties are all blank.
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:1→2 or
Rev:A→B. This is a comma-separated list if more than one change occurs (for
example, both quantity and revision changes might look like Qty:1→2,Rev:A→B).
• bl_quantity_change
Contains details of a quantity change (in other words, if Qty is a sub-string of
the bl_compare_change attribute). The change is stored as the two quantities
separated by an arrow (for example, 1→2).
• bl_revision_change
Contains details of the revision change (in other words, if Rev is a sub-string of
the bl_compare_change attribute). The change is stored as the two revisions
separated by an arrow (for example, A→B). If more than one revision of an item
exists in one of the BOMs then all the revisions are listed (for example, A,B→C).
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
chararacter 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.
These functions are only available 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.
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 Compare’s 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 window:
If:
( (output & BOM_compare_output_report) == 0)
{
BOM_compare_suppress (line1, BOM_compare_output_userexit );
return ITK_ok;
}
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.
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:
• 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.
#include <unidefs.h>
#include <iman.h>
#include <bom.h>
#include <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. Figure 8-9 counts the number of BOM lines (on the left or right
hand side) determined to be different by the compare:
/* 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
they’re not interesting here */
if ( BOM_compare_visit_engine( compare_context, NULL, NULL, count_bomlines_visit_set,
(void*) &results ) != ITK_ok )
{
return -1;
}
return results.count;
}
• BOMView revision
• Occurrence
• View type
• Note type
BOMView
In the figure:
• Item is the item to which this BOMView belongs, inquired by the
PS_ask_item_of_bom_view function.
• BOMView revisions are all of the revisions of this BOMView. They can be listed
using the PS_list_bvrs_of_bom_view function.
• ViewType specifies the type of this BOMView with the tag of a View Type
object. Use the PS_ask/set_bom_view_type functions to inquire or modify
its value, respectively.
• BOMView also inherits name and description from the workspace object, which
can be inquired and changed using the appropriate WSOM functions.
A BOMView is created by the PS_create_bom_view function. The name of the
BOMView must be unique for all BOMViews of the parent item. Be aware that no
initial revision is created, this is done by a call to the PS_create_bvr function.
A new or modified BOMView 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.
BOMView 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
BOMView revision referenced by that item revision. A revision of BOMView "A"
must specify the structure of a revision of the item that owns BOMView "A".
There is no one-to-one correspondence between item revisions and BOMView
revisions, because where two or more revisions of an item have the same structure
they may share references to the same BOMView revision. A new working item
revision based on a previous released revision retains a reference to the released
revision’s BOMView 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 BOMView at a time.
BOMView 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 revision’s data. For
example, to protect the structure from further modification while detailed
changes are still being made to a drawing.
Occurrences
The single level structure of an item revision is made up of a collection of links from
a BOMView revision (the parent) to the items which 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 manual.
Occurrence is not presented as a distinct class within Teamcenter, rather as
an attribute of BOMView revision. In the PS ITK module, occurrences are
always addressed through their parent BOMView revisions.
Precise/Imprecise
Alternates
Rather than referencing a single component item, an occurrence can contain links
to several alternate items (alternates). Alternates are interchangeable with one
other in the assembly. However, one of these alternates is specified as the preferred
alternate. All alternates of a single occurrence share the same attributes, the
attributes specified for the preferred alternate.
Any modifications the occurrence alternates is a modification to the BOMView
revision. Permanent modifications require write access to the BOMView revision.
Temporary modifications may be made during a Teamcenter session but cannot be
saved to the database.
The class attributes and methods for occurrence in the PS module are shown in
figure 8-12.
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.
View Type
Each BOMView 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.
Teamcenter provides a default View type. All BOMViews 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 figure 8-13:
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
figure 8-14:
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.
Adding Attributes
You can add attributes to PS objects using the PS ITK. 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.
Where Used
The PS ITK supplies three functions to produce where used reports on item revisions.
Each reports parent item revisions having a BOMView revision with occurrences
referencing the given item revision up to a specified number of levels.
• PS_where_used_all
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.
This chapter describes the Persistent Object Manager (POM), POM inheritance,
and the POM enquiry module.
• 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
The following sections describe class, attribute, instance, index, and tag.
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.
In figure 9-1, 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.
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 which 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).
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.
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.
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 user’s session, duplicates may exist.
For example, the POM_user class has a name attribute which 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 receiver’s tag can be different in value to the
sender’s as they are in different sessions.
Class Definition
The POM_define_class function defines a new class as a subclass of an existing
class. You can define new classes at your site by specifying the following for the
new class:
• A unique class name.
• A super class.
• Optionally, an application name, when it is required for the newly created class
to have certain operations performed on it by that named application.
The application name is a security feature. Operations on the instances
of that class, or at least the attributes of that class, are restricted to
the named application. The application identifies itself around the
operation. By keeping its registration code secret, which was given
during initialization, other applications cannot gain access to the classes
in a specified instance.
The new class inherits all the attributes defined for its superclasses.
To remove a class from the class tree, use the POM_remove_class function (the
schema is saved by this call). Removing the class ensures that it can no longer be
used to create new instances or to define new subclasses.
To remove a class:
1. Remove all of its subclasses.
You can now remove the class by calling the POM_remove_class function. To
use this function, the caller must be an Teamcenter system administrator. The
new schema, without this class and its subclasses, is saved when the POM_stop
function is called.
The POM_save_class function saves a new class.
Class_id
On creation, a class is given an identifier, the class_id. This is the internal reference
that the POM uses whenever that class is used in a function.
Initial Classes
When the POM is installed, the initial class hierarchy contains six classes. The
topmost class in this hierarchy and superclass of all POM classes is POM_object.
There are two direct subclasses of POM_object: POM_application_object
and POM_system_object. POM_system_object in turn has three subclasses:
POM_user, POM_group, and POM_member. Applications should define their
own classes using POM_application_object as their superclass, inheriting useful
attributes such as access control lists. Figure 9-2 shows the initial classes and their
relationship.
Attribute Definition
To define an attribute for a class, use the POM_define_attr function. The argument
of this function, descriptor, determines by description of the attribute whether:
• It must be uniquely valued.
• It is a class variable.
• It can be frozen.
• It can be written to/by, even if the class is application protected (for more
information, see Application Protection, later in this chapter).
The following functions are used to set the value (or NULL value) for an attribute
that has been defined to have lower and (or) upper bounds:
• POM_set_attr_lower_type
• POM_set_attr_lower_null
• POM_set_attr_upper_type
• POM_set_attr_upper_null
The bounds are closed. Therefore, the values specified for the bounds are themselves
legitimate. For example, if the lower bound is 0 (zero), then 0, 1, 2, and so on are
permissible, but -1, -2, and so on are not.
To set the initial value (or NULL value) for an attribute that has been defined to
have an initial value use the relevant function use one of the following functions:
• POM_set_attr_initial_type
• POM_set_attr_initial_null
For array-valued attributes, all the elements in the array take the same
lower and upper bounds and the same initial value.
Attribute_id
On creation, an attribute is given an identifier, the attr_id. This is the internal
reference that the POM uses whenever that attribute is used in a function.
Index Definition
To ease the search facility, a set consisting of one or more attributes can be specified
to be indexed.
The POM_define_index function defines an index by:
• Taking an existing class and a number of attributes which are already associated
with that class.
– The class.
To remove an index definition from the class definition, use the POM_remove_index
function.
Indexes have the following restrictions imposed on them by the mapping of the
RDBMS:
• They cannot index on Note attributes.
• They cannot define an index that spans class boundaries (in other words, class
to subclass).
• POM_ask_attr_lower_type
• POM_ask_attr_upper_type
• POM_ask_attr_initial_type
• POM_describe_index
• POM_indexes_of_class
• POM_indexes_of_attr
• POM_attr_id_of_attr
• Whether one class is anywhere in the class structure below a given class.
Create Instance
The POM_create_instance function allows you to create an instance of a specified
class.
It is possible to 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.
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.
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
caller’s 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 or any superclass.
The POM_load_instances function loads and creates copies of specified instances
that are all of the same 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 figure 9-3:
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
caller’s 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 caller’s 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 might have occurred since the user’s copy was made.
• When you decide to scrap all changes that have been made to the instance.
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.
Select Instance
If the application knows before loading an instance which attributes it intends
to manipulate, the application may choose to load the instance with only those
attributes. This is called selecting. The instance is loaded in the normal way, with
the normal rules for loading applied, except that attributes that are not selected are
not loaded. Any attempt to manipulate these unselected attributes are trapped
by the POM.
The advantage of selecting over loading is that selecting an instance takes less time
than loading the full instance. The functions used to select instances are:
• POM_select_instances
• POM_select_instances_by_enq
A selected instance can be turned into a fully loaded instance by refreshing it.
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.
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.
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.
• POM_create_enquiry_on_types
• 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.
It is not possible to order on either variable length arrays (VLA) or arrays.
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.
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
• 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.
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 non-array
attributes.
• 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.
• POM_string_to_tag
• POM_class_id_to_string
• POM_string_to_class_id
• POM_attr_id_to_string
• POM_string_to_attr_id
• POM_compare_tags
• POM_compare_dates
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.
• 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.
Create
The following functions create instances of users, groups and members:
• 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
• POM_init_group
• POM_init_member
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.
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 into the listed group.
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 user’s
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
into 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.
The POM_set_user_status function sets the status of the user. 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.
• POM_is_user_sa advises if the current user is logged into the POM under a
privileged group.
• 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.
Security
Teamcenter provides security through application protection and access control lists.
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
• 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.
• read
The privilege to read the instance.
• write
The privilege to modify the instance, which also implies read privilege.
• change
The privilege to change the access control in force.
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
timeouts and logins, and trap POM errors.
The only alternative to calling the POM_start function to start the POM module is
for the system administrator to log into the POM using the POM_start_modify
function. This function differs from POM_start in that it allows the system
administrator and only the system administrator, to modify the schema (in other
words, define classes and remove class definitions).
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.
Because of the severity of this operation, it can only work on one user at
a time.
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 caller’s changes to the database. Any changes to the
database by other users are unaffected. If other users have made changes which
prevent the caller’s changes being reversed (for example, deleted or changed values
in an instance in the database), then the rollback fails.
Timeouts
You can use the POM_set_timeout function to set a session wide timeout 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 timeout 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 timeout 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.
Control of Logins
The control of logins, 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 logins terminating
abnormally, the system administrator does have the authority to login 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.
Audit Trail
The audit trail is the logging of specific actions by POM, To do this, the POM calls
the general Teamcenter logging function with the POM_set_audit_action function.
The POM_ask_audit_action function returns what auditing is currently active.
Environmental Information
The POM_set_env_info function offer alternative methods of enabling and
disabling operations as explained in its description. This function sets the following
environmental information:
• Enable or disable rollback.
• 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).
Miscellaneous
This section highlight the 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.
• 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:
– non-array (for example, an integer)
– small array
– large array
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
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.
2. Find the class in Teamcenter or among other classes that you have defined that
is most like the one you want.
3. Write the schema definition file for your class, inheriting from the class you
located in step 2 and defining any attributes unique to your class.
• Initialize an instance of your class so that other classes can inherit from
yours.
Our example is for a class to represent a library of standard parts for a company.
Basically, a library should be like a folder:
• It needs to have a library type, either corporate, site or private.
/*
* Define for the class name
*/
#define LIBFL_CLASS_NAME "LibraryFolder"
/*
* Defines for the attribute names
*/
#define FLLIB_MEMBER_ATTRIB"member"
#define FLLIB_DATE_ATTRIB"last_update"
/*
* enums for the library member values
*/
typedef enum LIBFL_member_e {
LIBFL_corporate, /*indicates a corporate library folder*/
LIBFL_private, /*indicates a private library folder */
LIBFL_site/*indicates a site library folder */
} LIBFL_member_t;
Schema Definition
The next file, shown in figure 9-5, defines the schema for the LibraryFolder class.
Notice that it does not use the ITK_auto_login or ITK_init_module functions
because it must log in with the POM_start_modify function to modify the schema.
#include "iman.h"
#include "folderlib.h"
/*
*
*/
int main(
int argc, /* <I> number of command line arguments */
char* argv[]/* <I> list of command line arguments */
)
/*
* Description:
*This program will install a specialized FolderLand object in the POM
* database. This new object will store library information.
* Since this program is strictly calling POM, it does not require
* the use of ITK_user_main.
*-+
*/
{
int retcode = 0;
tag_t user_tag;
tag_tpom_obj_class_id;
int version,app_id, app_code;
tag_tsuper_class_id;
tag_tlibrary_folder_class_id;
tag_tlib_member_attr_id,lib_date_attr_id;
if (retcode == POM_ok)
{
/*
* Register the name of the application that will manipulate this
* object. This is to prevent any other application from accessing
* the object. Once an application is register, use the app_id and
* app_code change the application protection mode. Save
* these values for future use.
*/
if ((retcode = POM_register_application(LIBFL_APP_NAME,
"some_password", &app_id,
&app_code)) == POM_ok)
{
POM_identify_application (app_id, app_code, true);
/*
* Since we are going to inherit from Folder Manager , we need to
* get Folder Manager’s class id. The class name for Folder Manager
* is "Folder".
*/
POM_class_id_of_class ("Folder", &super_class_id);
/*
* Now define the new class LibraryFolder.
*/
POM_define_class (super_class_id ,
LIBFL_CLASS_NAME, LIBFL_APP_NAME ,
0, &library_folder_class_id);
/*
* Define the attributes for LibraryFolder.
*/
POM_define_attr(library_folder_class_id, FLLIB_MEMBER_ATTRIB,
POM_int, 0, NULLTAG, 1, 0, &lib_member_attr_id);
POM_define_attr(library_folder_class_id, FLLIB_DATE_ATTRIB,
POM_date, 0, NULLTAG, 1, 0, &lib_date_attr_id);
/*
* Save the new class to the database
*/
if ((retcode = POM_save_class(library_folder_class_id)) != POM_ok)
{
printf("Unable to save the new class.\n\r");
}
/*
* Turn on application protection, so that no one else can
* can manipulate the data definition for LibraryFolder class.
*/
POM_identify_application (app_id, app_code, false);
}
/*
* Log out of POM
*/
POM_set_logins(true);
POM_stop (true);
}
else if (retcode == POM_already_running )
{
printf("Unable to login as INFODBA.\n");
printf("No one can be logged in when running this program.\n\r");
}
else
{
printf("Error logging into POM as INFOMDBA. Error Code = %d\n\r",
retcode);
}
return (retcode);
} /*main*/
ITK Extension
The code shown in figure 9-6 extends the ITK to include functions which manipulate
instances of the LibraryFolder class. Be aware that there is a LIBFL_initialize
function, thus this class may also be further specialized.
* This file contains the C ITK functions for the LibraryFolder object.
* LibraryFolder is a subclass of Folder.
*
*-+
*/
#include "iman.h"
#include "folder.h"
#include "folderlib.h"
/*
* LibraryFolder Class Functions
*/
int LIBFL_create(
const char name[WSO_name_size_c + 1], /* <I> */
const char desc[WSO_desc_size_c + 1], /* <I> */
LIBFL_member_t member, /* <I> */
tag_t* lib_tag /* <O> */
)
/*
* Description:
* This function creates a LibraryFolder object. It will not be
* saved to the database until an explicit call to AOM_save() is
* made. A name and Library member must be specified.
*
* Function Return:
* A zero will be returned on success. Otherwise, an integer error
* code will be returned.
*
*-+
*
*/
{
int retcode = 0;
tag_t folderlib_id_class;
/*
* Get the class id for Folder and create a new instance of a
* LibraryFolder class.
*/
if ((retcode = POM_class_id_class(LIBFL_CLASS_NAME,
&folder_id_class)) == POM_ok)
if ((retcode = POM_create_instances(1,folderlib_id_class,
lib_tag)) == POM_ok)
{
/*
* Using the returned tag, initialize the object attributes.
*/
return(retcode);
} /*LIBFL_create*/
/*
*+-
*/
int LIBFL_initialize(
tag_t lib_tag, /* <I> */
const char name[WSO_name_size_c + 1], /* <I> */
const char desc[WSO_desc_size_c + 1], /* <I> */
LIBFL_member_t member /* <I> */
)
/*
* Description:
* This function initializes a LibraryFolder object. It is meant to
* be called after the creation of an instance of a subclass of
* LibraryFolder.
*
* Function Return:
* A zero will be returned on success. Otherwise, an integer error
* code will be returned.
*
*-+
*
*/
{
int retcode = 0;
tag_t attr_id;
{
/*
* Initialize the attribute’s value for this instance of LibraryFolder
*/
retcode = POM_set_attr_int(1,&lib_tag,attr_id,(int) member);
/*
* Using the returned tag, initialize the superclass object attributes.
* Since a LibraryFolder is a subclass of Folder, it inherits the
* attributes from the Folder class.
*/
return(retcode);
} /*LIBFL_initialize*/
/*
*
*+-
*/
int LIBFL_set_member(
tag_t lib_tag, /* <I> */
LIBFL_member_t member /* <I> */
)
/*
* Description:
* This function sets the library member attribute. The attribute
* can be set to the following values:
*
* LIBFL_corporate
* LIBFL_private
* LIBFL_site
*
* Function Return:
* A zero will be returned on success. Otherwise, an integer error
* code will be returned.
*
*-+
*/
{
int retcode;
tag_t attr_id;
/*
* Get the attribute id for "member" attribute.
*/
if ((retcode = POM_string_to_attr_id((char *) FLLIB_MEMBER_ATTRIB,
&attr_id) == POM_ok))
{
/*
* Set the attribute’s value for this instance of LibraryFolder
*/
retcode = POM_set_attr_int(1,&lib_tag,attr_id,(int) member);
}
return (retcode);
} /*LIBFL_set_member*/
/*
*
*+-
*/
int LIBFL_ask_member(
tag_t lib_tag, /* <I> */
LIBFL_member_t *member /* <O> */
)
/*
* Description:
* This function gets the current value of member attribute. The attribute
* can be one of following values:
*
* LIBFL_corporate
* LIBFL_private
* LIBFL_site
*
* Function Return:
* A zero will be returned on success. Otherwise, an integer error
* code will be returned.
*
*-+
*/
{
int retcode;
tag_t attr_id;
logical is_it_null, is_it_empty;
/*
* Get the attribute id for "member" attribute.
*/
if ((retcode = POM_string_to_attr_id((char *) FLLIB_MEMBER_ATTRIB,
&attr_id) == POM_ok))
{
/*
* Get the attribute’s value for this instance of LibraryFolder
*/
retcode = POM_ask_attr_int(lib_tag,attr_id,(int *) member,
&is_it_null,&is_it_empty);
}
return (retcode);
} /*LIBFL_ask_member*/
/*
*
*+-
*/
int LIBFL_set_last_accessed_date(
tag_t lib_tag, /* <I> */
date_t date /* <I> */
)
/*
* Description:
* This function sets the last accessed date attribute.
*
* Function Return:
* A zero will be returned on success. Otherwise, an integer error
* code will be returned.
*
*-+
*/
{
int retcode;
tag_t attr_id;
/*
* Get the attribute id for "last_update" attribute.
*/
if ((retcode = POM_string_to_attr_id((char *) FLLIB_DATE_ATTRIB,
&attr_id) == POM_ok))
{
/*
* Set the attribute’s value for this instance of LibraryFolder
*/
retcode = POM_set_attr_date(1,&lib_tag,attr_id,date);
}
return (retcode);
} /*LIBFL_set_last_accessed_date*/
/*
*
*+-
*/
int LIBFL_ask_last_accessed_date(
tag_t lib_tag, /* <I> */
date_t *date /* <O> */
)
/*
* Description:
* This function gets the last accessed date attribute.
*
* Function Return:
* A zero will be returned on success. Otherwise, an integer error
* code will be returned.
*
*-+
*/
{
int retcode;
tag_t attr_id;
logical is_it_null, is_it_empty;
/*
* Get the attribute id for "last_update" attribute.
*/
if ((retcode = POM_string_to_attr_id((char *) FLLIB_DATE_ATTRIB,
&attr_id) == POM_ok))
{
/*
* Get the attribute’s value for this instance of LibraryFolder
*/
retcode = POM_ask_attr_date(lib_tag,attr_id,date,
&is_it_null,&is_it_empty);
}
return (retcode);
} /*LIBFL_ask_last_accessed_date*/
POM enquiries are not the same as saved queries. They are completely
different mechanisms.
There are actually two different enquiry systems—a newer one and an older one. You
should use the newer one with the calls that begin withPOM_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.
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. 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 in this section 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.
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 you’ve 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.
• 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:
– 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
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.
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.
7. Clean up.
Below are a number of examples that illustrate these steps for different cases.
This is a very simple case. This example finds all the workspace objects whose type
is equal to a string that is passed in. Figure 9-7 shows a single bind variable to
compare strings.
Note on Attributes
In general, attributes are referred to by two strings: the name of the class you are
interested in and the attribute name. These values are the same as the definitions in
the schema and do not have to reflect the underlying database table structure. For
example, if you want to get the object_desc attribute of an item then you would
refer to it using the Item class and object_desc attribute. It does not matter that
the object_desc attribute is really on the workspaceobject parent class or what
the 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.
Housekeeping
As mentioned above, 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
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 */
…
A join is when you link one table or object to another. For this example, we use
entries in the Process Stage List array and use them to join to EPM tasks. Figure
9-8 shows how they relate to each other.
/* 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" )
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. Ffor 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 thePOM_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.
• 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.
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 ]
Building Expressions
The POM enquiry system APIs contain a list of functions that can be used to build
expressions. They are shown in table 9-1.
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 figure 9-10:
void ***report;
int n_rows, n_cols, row, column;
const char *select_attr_list[] = { "object_name", "object_type"};
date_t aDate;
/*create a query*/
POM_enquiry_create("aEnqId");
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 table 9-2 below 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 above SQL statement, the object_name and user_name
attributes do not belong to the same class. Therefore we need to call the
POM_enquiry_add_select_attrs function twice, as shown in figure 9-11.
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
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 figure 9-12:
/*create a query*/
POM_enquiry_create ("a unique query id")
/*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;
date_list[1]=aDate2;
/*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");
ORDER BY Clause
As can be seen from the above 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 figure 9-13.
/* Create a query*/
POM_enquiry_create ("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
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 figure 9-14:
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
/*Create a subquery.*/
POM_enquiry_set_sub_enquiry ( "a_unique_query_id", "subquery_unique_id" );
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 figure 9-15.
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
Use of pseudo_class
For example, if you want to find the latest released version 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.
You can only create pseudo-classes for VLAs or LAs attributes.
The POM enquiry APIs required to create this query are shown in figure 9-16:
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
Use of Set-Expression
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 figure 9-17.
/* Create a query*/
POM_enquiry_create ("a_unique_query_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");
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 figure 9-18.
/* Create a query*/
POM_enquiry_create ("a_unique_query_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");
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 figure 9-19.
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
/* Create a subquery*/
POM_enquiry_set_sub_enquiry ("a_unique_query_id", "subquery_unique_id" )
Special Operators
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 figure 9-20.
/* 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")
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.
POM_enquiry_cpid_of can only be used with typed or untyped_reference
type attributes.
/* Create a query*/
POM_enquiry_create ("a_unique_query_id")
POM_enquiry_countdist
If you want to create the expression COUNT(DISTINCT item.puid ), you can use
the enquiry APIs as shown in figure 9-23
The same apply to MAX, MIN, AVG, and SUM except that these apply to different
attributes of the class, not the puid.
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
Table 9-2 shows the operators that are supported in the POM enquiry module.
SWH means [S]elect [W]here [H]aving clauses and [-] means the operator is
applied to the outer query.
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.
10 Workflow
10 Workflow
This chapter describes the Enterprise Process Modeling (EPM) module and the
Cascade Release (CR) application.
This section describes how to 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 window and
the areas that require programming to meet site-specific requirements.
• Task
• Action
• Attachment
• Business rule
Jobs
A job is the runtime 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 window. You can instantiate a procedure and create a job programmatically
using the EPM_create_job function.
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 runtime. 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.
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 window.
Actions can be either displayed during runtime or triggered programmatically. To
display the action string of the current action applied to a task during runtime, 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.
Predefined Actions
EPM comes with predefined actions that can occur on any task. These predefined
actions are as follows:
You can define your own actions by modifying the iman_text.uil file in the
IMAN_ROOT/lang/ directory. For example, if you want to add the Mail action, you
need to add the following line to the iman_text.uil file:
EPM_action_1001 : exported "Mail"
The value of the number in the EPM_action_number line must be greater than
1000 because EPM_user_action is defined to be 1000 in the epm.h file. Compile
the iman_text.uil file using the UIL compiler after you finish your modification.
For maintainability, you might also want to define a MAIL macro in your local
header file. For example:
#define MAIL (EPM_user_action + 1)
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
Attachments
Attachments are other objects that are associated with the task during runtime.
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 manual.
If you want task comments to display in the thin client user interface, you
must use customize your workflow using ITK.
For ease of maintenance, define the ECN macro in your local header file. For
example:
#define ECN (EPM_user_attachment +1)
• 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.
The action handler must return an int status code that can be compared to
ITK_ok to determine if the handler was executed successfully.
Steps to Follow
With the ITK programming standards in mind, follow the steps below to create
your own action handler:
1. Write the action handler program following the standard interface mentioned
earlier and the ITK programming standards.
if(IMAN_number_of_arguments(msg.arguments)>0)
{/* get first argument */
arg = IMAN_next_argument(msg.arguments);
system(arg);
}
return err; /*return an ITK error code if an error/
occurred*/
}
The first call to the IMAN_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 IMAN_next_argument gets the next argument
on the list. Use the IMAN_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.
EPM_decision_t
• 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
• proposed_action
Action that was triggered
• arguments
Argument specified in the procedure
• tag
System data
Steps to follow
With the ITK programming standards in mind, follow the steps below to create
your own rule handler:
1. Write the rule handler program following the standard interface mentioned
earlier and the ITK programming standards.
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
}
All rule handlers must be registered. The following example illustrates how you
would register a rule handler.
The example shown in figure 10-4 uses the USER_epm_init_module function
which registers a function called EPM_check_responsible_party through the
EPM_register_rule_handler function as the check-responsible-party handler.
When defining tasks interactively, the registered name of the
handler-check-responsible-party should be used 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("check-responsible-party", "",
EPM_check_responsible_party);
return s;
}
USER_gs_shell_init_module()
{
...
USER_epm_init_module();
}
• 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.
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.
– 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.
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="validation_rule.xsl"?>
<Rule_Set
name="Test_rule_set_1"
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>
<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>
Figure 10-6 shows how to call validation rule APIs to perform a validation result
check with the validation rules.
/**********************************************
* 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
*/
EPM Hints
This section outlines some helpful hints you can use when working with EPM.
.........
.........
return err;
}
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:
if(msg.action > EPM_perform_action)
return ITK_ok;
as follows:
int my_action_handler(EPM_action_message_t msg)
{
if(msg.action > EPM_perform_action)
return ITK_ok;
Inbox Queries
There are three queries that can be used to determine which tasks show up in the
Inbox:
• Show all but completed and skipped tasks.
You can change which query workspace uses by modifying the k_inBox in the
flcommons.uih file, then recompiling the flwindow.uil and homeflwindow.uil
files. The following is found in the flcommons.uih file:
Without the check-completion rule handler, Task A and Task B both start when Task
1 is started (in other words, parallel tasks).
Consider also the following example where all subtasks (C, D, E and F) start as soon
as Task 2 is started by default:
Task 2
---Task C
---Task D
---Task E
---Task F
If you want Task E to wait for Task F to complete, you must add the check-completion
rule handler as follows:
Task 2
---Task C
---Task D
---Task E
Start
Rule check-completion Task F
---Task F
This chapter describes how to import and export objects as well as Multi-Site
Collaboration programming techniques.
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, BOMView and BOMView 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 BOMView and BOMView revision objects.
All Teamcenter files that the dataset represents are exported, including the
operating system files that these encapsulate and the dataset’s 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
When an object is imported, the owner is the user who performed the import. The
group is the group in which the owner logged into to perform the import. Even
though the user is the owner object, they might not be able to modify the object. This
occurs if the site ownership indicates that another site is the owner.
In general with import, object site ownership takes precedence in determining who
has the right to update the object.
• 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.
All released objects are exported with their status (for example, Released
to Manufacture).
• It is the responsibility of the system manager to set up the list of other sites
which are known to the local site.
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:
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.
Items need to have unique ID’s. 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.
These do not have unique names, therefore there are no problems when importing
objects.
– The item can be deleted from the database only if the item itself is selected.
You cannot delete any of the item revisions alone.
• When an item is imported with read/write privileges (with site ownership), then
the following rules apply:
– 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.
– 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.
– 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 manual.
Imported objects are in the same folder structure as they were when
exported.
Multi-Site Collaboration
This section discusses ITK programming techniques and considerations unique to a
Multi-Site Collaboration environment.
2. In the Options dialog window, accessed from the Edit menu in My Navigator,
define the IMAN_default_export_sites preference with a list of the desired
target sites. For example:
IMAN_default_export_sites=
SITE1
SITE2
Caveats
Developing Forms and Customizing the Properties Display Using XML Style
Sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16
Using Predefined Style Sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16
Modifying a Predefined Style Sheet . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-17
Creating a New Style Sheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18
Style Sheet XML Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-19
XML Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-20
Display Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-26
Rendering Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-26
Rendering Hints, Rendering Style, and JavaBeans . . . . . . . . . . . . . . 12-27
Customizing Property Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-30
Examples of XML Style Sheet Definitions and Renderings . . . . . . . . 12-30
Property Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-33
This chapter describes the processes used to create forms in the Teamcenter
Engineering rich client.
This chapter should be read from two perspectives. The first perspective is the
actual creation of forms within the rich client. It takes very little work and requires
no programming ability to create and display a form. The second perspective is that
of the programmer, which focuses on the techniques used to develop sophisticated
solutions.
A form is a logical storage mechanism that supports captured, informative, and
derived data. Captured data are the fields within a form in which users enter data;
these are generally required fields. Business rules often dictate that certain fields
be populated before the form is created. Informative data are read-only fields that
appear within the form and cannot be modified by the user. Derived data are the
fields within a form that are the sum or combination of other fields, or PDM data
that is composed and displayed within the form. Derived data typically cannot
be modified.
Forms capture information that users reference and view. These forms store data,
such as work order, ECO, or ECN information. Information contained in forms can
be used for queries. Companies typically use forms to:
• Capture and store information for work orders, ECOs, or ECNs. This is the most
common use of forms.
Displaying a Form
When a form is displayed, the UI definition for the form is constructed, populated,
and placed within a container. In the rich client, a form can be displayed under two
paradigms: dialog and viewer. The dialog displays when the form is opened using
the Open menu or the form is double-clicked (figure 12-3). The viewer paradigm
is used when the form is selected and the Viewer tab is active (figure 12-4). The
contents of nonwritable form are displayed as read-only. If the user has write access,
then the form can be edited.
• JavaBean
Allows you to define forms using JavaBeans and an IDE (such as Eclipse) to
present form properties. Each bean knows how to display and save a specific
property type. This method is less complex than the abstract rendering method
but still requires some programming knowledge.
• Automatic Forms
Allows you to display forms that have no associated interface definition. The
interface is created automatically as the form is displayed, based on the storage
fields identified within the form POM class.
ItemRevision\ Master.FORMJAVARENDERING=com.ugsolutions.iman.form.ItemRevisionMaster
package com.mycom.iman.form;
import javax.swing.*;
import com.ugsolutions.iman.kernel.*;
import com.ugsolutions.iman.stylesheet.*;
import com.ugsolutions.util.*;
{
private JTextField projectId;
private JTextField serialNo;
private IMANProperty piProperty;
private IMANProperty snProperty;
private IMANComponentForm form;
private IMANSession session;
/**
* This method is the constructor for MyForm given the IMANComponent of the
* form component.
*
* @param IMANComponentForm -The IMANComponentForm representing this form.
* @return void...Constructor
*/
public MyForm ( IMANComponentForm c)throws Exception
{
super ( c );
form = c;
session = c.getIMANSession();
/**
* This method is used to provide the loading of the form properties
* from the database to the UI of the form itself.
*
* @return void
*/
public void loadRendering() throws IMANException
{
initializeUI(); // Construct the UI and it’s components
piProperty = form.getFormIMANProperty("project_id");
snProperty = form.getFormIMANProperty("serial_number");
projectId.setText ( piProperty.getStringValue() );
serialNo.setText ( snProperty.getStringValue() );
}
/**
* This method is used to provide the saving of the form properties
* from the form class definition to the database.
*
* @return void
*/
public void saveRendering()
{
try
{
piProperty.setStringValueData ( projectId.getText() );
snProperty.setStringValueData ( serialNo.getText() );
ps[0] = piProperty;
ps[1] = snProperty;
form.setIMANProperties(ps);
}
catch ( IMANException ex )
{
}
}
/**
* This method is used to construct and initialize the UI of the form
* which will be setup to be populated with data.
*
* @return void
*/
private void initializeUI()
{
setLayout ( new VerticalLayout() );
JPanel mainPanel = new JPanel( new PropertyLayout());
mainPanel.setOpaque(false);
3. Register the form with the rich client, by one of the following methods:
• Edit the stylesheet_user.properties file located in the portal.jar file.
If you want to add a red triangle on the form to note a required field, add the
following code:
if (required)
{
propertyRenderer = new JLabel( propValue )
{
public void paint(Graphics g)
{
super.paint(g);
Painter.paintIsRequired(this, g);
}
};
}
General Comments
Example of a Basic UI Form is simplistic but shows the relationship of the different
methods and the purposes they serve. The source code in this example was created
manually.
The form UI is not limited to creation using an integrated development environment
(IDE) or to the use of any Java component. Third-party Java components can be
used within the form.
An IDE, such as Eclipse or Visual Café, can be used to generate the contents of the
form. Once created, you need only add the code required to read the property values
from Teamcenter Engineering and set the property values within the associated
component on the panel. Other components, such as LOVButton and DateButton,
make it easier to render the form properties.
If you upgrade from a previous version of Teamcenter Engineering that used the note
attribute in the form storage class, instances created from that class will continue to
use the note attribute. If you create a new storage class, it uses the string attribute,
and instances created from that class use the string attribute.
Starting with Teamcenter Engineering 2005, you should use the new style sheet
package (com.ugsolutions.iman.stylesheet) instead of the old form package
(com.ugsolutions.iman.form). The old form package will be deprecated
in a later release. If you want to still use the old custom forms in the new
package, move the entries you added to the form_user.properties file to the
stylesheet_user.properties file.
Form Events
When a form is displayed, the size is governed by the standard of preferred size for a
dialog. However, it may be necessary to control the dialog size prior to displaying
the form. In this event, implement the InterfaceRendererEvent interface within
the form display class. This interface forces the implementation of two methods:
dialogDisplayed (OpenFormDialog dlg, boolean state). The method is called
before the dialog is displayed. It is the place where the setBounds() method for
the dialog can be called.
When a form is displayed, the okToModify() method is invoked. If the form
is modifiable, it is constructed and displayed as designed. However, if the form
is not modifiable, logic is executed to determine what should or should not be
editable. When a read-only form is displayed, the components shown in table 12-1
are modified.
When a form is not modifiable, all Container objects, such as JTabbedPane, are
ignored and the remaining components are disabled. This is because Container
objects allow users to traverse and work through them to view the data. You may
want to control the read-only ability of a component within a form, in which case you
must override the read-only logic by implementing the InterfaceRendererEvent
interface and providing body to the setReadOnly() method.
// User written
public MyPanel ( IMANComponentForm f )
{
}
When the form loads, the system looks first for the constructor with a reference
to the IMANComponentForm component. If one is found, it is used. If not, the
default constructor is used.
The properties of each form bean are described in Property Beans, later in this
chapter.
Once you have created the component, all other JavaBean rules apply. For example,
you can attach icons for reference within an Integrated Development Environment
(IDE), such as Eclipse, and attach property rendering rules.
To perform checks prior to loading the form beans, override the checkObject
method as given follows:
public void checkObject() throws Exception
{
//required checks
}
All IDEs that support JavaBeans work with the form beans.
To increase the efficiency of form beans, UGS recommends that you also implement
the InterfaceBufferedPropertyComponent class. This requires a method that
has the following signature:
public IMANFormProperty saveProperty ( IMANComponentForm f )
throws Exception
This method should only use the setValue<type>Data calls to the form property
and return it. Therefore, all properties in the form bean system are collected and
saved in one call. This increases the efficiency of the form bean.
UGS provides both save() and saveProperty() methods to allow for flexibility in
form storage. All form beans delivered with Teamcenter Engineering utilize the
saveProperty() method. If you choose to override any of the base form beans, UGS
recommends that you override the saveProperty() method. If you override the
save() method in the base beans, Teamcenter Engineering uses your save() method
first over the saveProperty method.
This is accomplished using introspection. The bean is analyzed to determine if
there is an overridden save() method. If so, it is assumed that you want to use this
method over the saveProperty() method. This does not apply when you implement
your own form bean, because your form bean provides the implementation of the
save() method and is not considered to be overridden.
• Form
• Item
• Item revision
• Group
• User
• Role
• Site
• Group member
• Volume
• EPM job
• IMAN file
• Tool
• Reservation
The registration information is stored in the preference; each object type has two
entries used to display regular properties, as follows:
type-name.RENDERING
The value of this key is the dataset name or the dataset UID used to display
properties of this type of object:
dataset-name/uid>.REGISTEREDTO
The value of this key is the type name for which this dataset is registered. Therefore,
the value for type-name.RENDERING will be the dataset name/UID and the value for the
dataset-name/uid.REGISTEREDTO will be the type name.
You can verify the registration of forms in the rich client interface, as follows:
1. In one of the rich client applications, choose Options from the Edit menu.
Teamcenter displays the Options dialog window.
2. Click the Index link in the lower-right portion of the window. Teamcenter
displays the Preferences pane.
3. Enter form in the Search on preference name field and click the Search button
. Teamcenter displays the preferences that begin with form in the Preferences
list.
If no rendering registration is found for the currently selected type, the system
searches the hierarchy to determine if a rendering is registered to any of the parent
classes or parent types. If one is found, that rendering is honored.
3. Select the dataset and click the Viewer tab. Teamcenter displays the contents of
the XML file in the Style Sheet Viewer.
4. Choose the object type to which this style sheet will be registered from the
Registered Type list.
5. Choose one of the style sheet type options, either Property or Form.
8. Select an object that uses the style sheet and display the properties of the object
or open the form to verify the modifications to the style sheet.
b. Click the Import button. Teamcenter displays the Import File dialog window.
c. Locate and select the XML file in your operating system directory and click
Import. Teamcenter displays the XML file in the Named References dialog
window.
d. Click Close.
If you are a user with DBA access, you can use the viewer to create, modify, and
register the XML definition for a certain type object. If you do not have DBA access,
you can view the XML definition, but you cannot modify it.
Registration information is stored in a site preference. The scope of the preference is
read as ALL, which allows customers to manually modify the registration to apply to
a specific, user, group, or role, and those preferences are read accordingly.
XML Elements
The XML file used to define the property display must include the elements and
attributes shown in figure 12-12:
<rendering version=”1.0”>
<page titleKey=”general” title=”General” format=”OneColumn”>
<property name="project_id" icon=”images/group.gif”/>
<property name="serial_number" renderingHint="textfield" renderingStyle=”headed”/>
<property name="item_comment" renderingHint="textarea" column=”30” row=”5”/>
<property name="user_data_1" renderingHint="lovcombobox" renderingStyle=”titled”
border=”true” />
<separator />
<property name=”user_data_1” />
<property name=”user_data_2” />
<break />
</page>
<page format="TwoColumn">
<firstcolumn>
<property name="item_id" />
<property name="item_revision_id"/>
<property name="object_name" />
<property name="object_string" />
<property name="object_type" />
<separator />
<property name="last_mod_user"/>
<property name="owning_group" />
<property name="owning_user" />
</firstcolumn>
<secondcolumn>
<image />
</secondcolumn>
</page>
<page>
<all type=”property” />
</page>
</rendering>
title
The default string of the title
for this tab. This attribute
is used when the string in
title.key is not found in the
locale file. This is a required
attribute. This is supported in
both the rich client and thin
client.
format
The format to be used for
this page. This attribute
can have one of these
values: OneColumn or
TwoColumn. This attribute
is optional. If not defined,
the OneColumn form is
used. OneColumn and
TwoColumn are supported
in both the rich client and thin
client. For more information,
see Display Format, later in
this chapter.
renderingHint
Specifies the component
used to render this property.
This is an optional attribute.
If not defined, the default
render is used based on
the property type. For a
list of rendering hints, see
Rendering Hints, Rendering
Style, and JavaBeans, later in
this chapter.
• Headed
This is the default
rendering style. The
property name is
displayed on the left
followed by the property
value renderer. This is
supported in both the rich
client and thin client.
• Headless
This style renders only the
property value without
displaying the property
name in front of it. This is
supported in both the rich
client and thin client.
• Titled
The property name is
displayed on the top of the
property value renderer.
This is supported in both
the rich client and thin
client.
border
Determines whether the
border is displayed. Valid
values are true and false.
This works only with the
titled style. This is supported
in both the rich client and thin
client.
row
This attribute applies only to
the textarea elements. It sets
the number of the rows for the
element. This is supported in
both the rich client and thin
client.
separator Adds a separator in None.
the panel. This is
supported in both the
rich client and thin
client.
break Inserts a break in None.
the panel. This is
supported in both the
rich client and thin
client.
firstcolumn Applies only to None.
the TwoColumn
format. The properties
defined within this
tab are added to the
left column of the
TwoColumn format.
This is supported in
both the rich client
and thin client.
secondcolumn Applies only to None.
the TwoColumn
format. The properties
defined within this
tab are added to the
right column of the
TwoColumn format.
This is supported in
both the rich client
and thin client.
Display Format
There are two display formats: OneColumn and TwoColumn.
OneColumn This is the format used in the current property display. Each row
displays one property (figure 12-13). This is the default format
if no format is defined.
Rendering Style
Each type of renderer supports three styles: headed, headless, and titled.
Headed Displays the property name on the left followed by the property
value renderer. This is the default rendering style.
This style has two components (figure 12-15), the
PropertyNameLabel JavaBean for the property name and the
PropertyrenderingHint JavaBean for the renderer (for example,
PropertyTextField or PropertyTextArea).
The JavaBeans used depend on the specified rendering hint and rendering style.
Table 12-3 lists the JavaBeans used based on the hint and style definition. All
renderer hints are supported in the rich client. If the rendering style is not defined,
the default style is headed.
Renderer Supported in
Hint Thin Client? Rendering Style JavaBeans
textfield Yes Headed or headless PropertyTextField
Titled TitledPropertyTextField
textarea Yes Headed or headless PropertyTextArea
Titled TitledPropertyTextArea
Titled TitledPropertyCheckbox
Titled TitledPropertyRadioButton
Renderer Supported in
Hint Thin Client? Rendering Style JavaBeans
radiobutton Yes – Rendered Headed or headless PropertyRadioButton
optionlov using same OptionLov
component as
string LOV
array
Titled TitledPropertyRadioButton
OptionLov
togglebutton Yes – Rendered Headed or headless PropertyToggleButton
optionlov using same OptionLov
component as
string LOV
array
Titled TitledPropertyToggleButton
OptionLov
button Yes Headed or headless PropertyButton
Titled TitledPropertyButton
label Yes Headed or headless PropertyLabel
Titled TitledPropertyLabel
slider No Headed or headless PropertySlider
Titled TitledPropetySlider
panel Yes – Rendered Headed or headless PropertyPanel
using separators
Titled TitledPropertyPanel
objectlink Yes – Rendered Headed or headless PropertyObjectLink
as a textfield
Titled TitledPropertyObjectLink
lovbutton Yes – Rendered Headed or headless PropertyLOVButton
as regular LOV
Titled TitledPropertyLOVButton
lovcombobox Yes – Rendered Headed or headless PropertyLOVCombobox
as regular LOV
Titled TitledPropertyLOVCombobox
longtext Yes – Rendered Headed or headless PropertyLongText
as textarea
Titled TitledPropertyLongText
Renderer Supported in
Hint Thin Client? Rendering Style JavaBeans
array Yes – Date, Headed or headless PropertyArray
String
(textarea),
String LOV,
typed reference
(UID) LOV are
supported
Titled TitledPropertyArray
Default Renderers
Table 12-4 displays the default renderer for each type. If the rendering hint is not
provided, the default renderer is used.
If there is an LOV attached to the property, the lovcombobox is used unless the
rendering hint does apply to an LOV.
Each rendering hint has a key defined in the stylesheet.properties file for the class
path of the JavaBean. You can plug in your own bean by overwriting the entry in the
properties file to replace the default JavaBean or you can add new entries for custom
JavaBeans. The key has following format:
rendering-hint.DEFINITION
<page title="All">
<all type="property"/>
</page>
</rendering>
Figure 12-18 shows the User Properties dialog resulting from the XML definition in
figure 12-17.
Figure 12-20 shows the Item Properties dialog resulting from the XML definition in
figure 12-19.
Property Beans
The following table lists JavaBeans that you can use to customize the properties
display:
JavaBean Description
PropertyNameLabel Renders the name of a property (figure 12-21). By specifying
the name property, it shows either the displayable name or real
name of the property according to the setting. This bean can be
used along with other beans that display the property value.
JavaBean Description
ProperyTextField Renders any nonarray type property, except reference/relation
type properties (figure 12-22). This bean wraps the rendering of
the given POM property into JTextField. Upon saving, the bean
attempts to convert the string to the corresponding property
type. If it cannot convert the string to the required type, an
exception is thrown.
JavaBean Description
PropertyTextArea Renders any nonarray type property except reference/relation
type. This bean wraps the rendering of the given POM property
into the JTextArea, and is generally used for longer text (figure
12-24). Upon saving, it attempts to convert the string to the
corresponding type. If it cannot convert the string to the required
type, an exception is thrown.
JavaBean Description
PropertyButton Renders any nonarray type property into the text and icon of
the button (figure 12-26). The value of the property is displayed
as the button text. For the reference/relation type property, it
also attempts to display the icon associated with the reference
value. Users cannot change the button text; therefore, save does
not apply to this bean.
JavaBean Description
mandatory
Indicates whether the property is required. If true, a red
astral is displayed in the upper-right corner of the field.
TitledPropertyLabel Displays the property name above the label (figure 12-28). This
bean is similar to the PropertyLabel bean, and it actually
contains two beans: PropertyNameLabel and PropertyLabel.
JavaBean Description
TitledPropertySlider Displays the property name above the slider (figure 12-30).
This bean is similar to the PropertySlider bean, and it
actually contains two beans: PropertyNameLabel and
PropertySlider.
JavaBean Description
bordered
Indicates whether a border is drawn around the button.
JavaBean Description
TitledProperty Displays the property name above the checkbox (figure 12-34).
Checkbox This bean is similar to the PropertyCheckbox bean and
actually contains two beans: PropertyNameLabel and
PropertyCheckbox.
JavaBean Description
saveOnlyWhenSelected
Indicates to save only when the button is selected or to
always save.
TitledProperty Displays the property name above the button (figure 12-36). This
RadioButton bean is similar to the PropertyRadioButton bean.
JavaBean Description
saveOnlyWhenSelected
Indicates to save only when the button is selected or to
always save.
TitledProperty Displays the property name above the button. This bean is similar
ToggleButton to the PropertyToggleButton bean. Figure 12-38 illustrates an
implementation of the TitledPropertyToggleButton bean.
JavaBean Description
lovName
Specifies the name of the LOV that the bean uses. If
undefined, the LOV information is retrieved from the
property descriptor.
TitledProperty Displays the property name above the LOV button (figure
LOVButton 12-40). This bean is similar to the PropertyLOVButton bean
and actually contains two beans: PropertyNameLabel and
PropertyLOVButton.
JavaBean Description
mandatory
Indicates whether the property is required. If true, a red
astral is displayed in the upper-right corner.
modifiable
Indicates whether the property is modifiable. If not, the
combo box is disabled.
lovName
Specifies the name of the LOV that the bean will use.
If undefined, the LOV information is retrieved from the
property descriptor.
TitledProperty Displays the property name above the LOV combo box (figure
LOVCombobox 12-42). This bean is similar to the PropertyLOVCombobox
bean.
JavaBean Description
modifiable
Indicates whether the property is modifiable. If not, the
checkboxes are disabled.
lovName
Specifies the name of the LOV that the bean will use.
If undefined, the LOV information is retrieved from the
property descriptor.
TitledPropertyCheckbox Displays the property name above the checkboxes (figure 12-44).
OptionLov This bean is similar to the PropertyCheckboxOptionLov
bean.
JavaBean Description
TitledPropertyRadio Displays the property name above the buttons (figure 12-46).
ButtonOptionLov This bean is similar to the PropertyRadioButtonOptionLov
bean.
JavaBean Description
buttons. The PropertyPanel is designed for special behavior
beyond the scope of the other property beans described in this
manual.
TitledPropertyPanel Displays the property name above the panel. This is the same
as the PropertyPanel bean.
PropertyObjectLink This bean renders reference type properties. A popup menu is
provided for users to modify the value (figure 12-49). If the value
is not modifiable, the popup menu is not available. When the
link is clicked, the system displays a dialog with properties of
this reference component.
JavaBean Description
PropertyLongText This bean can be used with any string or note type properties,
but is generally used to render text with lengths over 2500
characters. It contains a text area and a button. The long text
dialog is displayed by clicking the button, making it easier to
browse the text (figure 12-51).
JavaBean Description
TitledProperty Displays the property name above the long text panel (figure
LongText 12-52). This bean is similar to the PropertyLongText bean.
JavaBean Description
PropertyArray Renders all array type properties. It is composed with a list box
and buttons to access the values in the list box (figure 12-54).
Based on the type of the property, a different renderer is used for
modifying or adding values. If the property is read only, users
cannot enter edit mode.
JavaBean Description
modifiable
Indicates whether the property is modifiable. If not, the edit
button is not available and the user cannot enter edit mode.
TitledPropertyArray Displays the property name above the property array (figure
12-55) and is similar to the PropertyArray bean.
JavaBean Description
You can define your own errors and error messages for display in Teamcenter
Engineering. Once these errors are defined, the appropriate error messages are
displayed or reported through the ITK for user-defined errors.
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.
Prior to version 8.1, custom error strings were stored in UIH file. You
can convert UIH files to XML with the uih_to_xml utility, located in the
IMAN_ROOT\bin directory. For additional information, see the Utilities
Reference manual.
2. Add the #define statement for your error message in your code using the
following syntax:
#define USER_ERROR_NAME (EMH_USER_error_base + nnn)
where nnn is your error number. For example, you can define a connection
failure error with a number of 10 as follows:
6. In your copy of the ue_errors.xml file, add a line to define the error string
corresponding to your custom message. Type the text within a pair of error tags
in the file. If you want to use a substitution marker, use %n$. For example:
<error id = "10">Unable to connect %1$</error>
14 Mechatronics
14 Mechatronics
This chapter provides background information required to use ITK APIs to create
and manipulate Mechatronics objects.
Connection_Terminal
Electrical connections PSConnection
Network
Connection
GDELink
Routes RouteNode
RouteSegment
RouteCurve
RoutePath
RouteLocation
RouteLocationRev
Allocations Allocation
For more information about these objects, see the Integration for Wiring Harness
Design Tools manual.
The following relationships allow you to associate fundamental objects:
• Implemented By
• Realized By
• Connected To
• Routed By
• Device To Connector
• Assigned Location
• Associated System
• Redundant Signal
• Process Variable
For more information about these relationships, see the Integration for Wiring
Harness Design Tools manual.
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
• GDELink_default_type
• TCENG_releasable_logical_types
• HRN_part_data_relation_primary
• HRN_wire_length_data_relation_primary
• HRN_fixing_assignment_relation_primary
• 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 Integration for Wiring Harness Design
Tools manual or the Configuration Guide.
Object Model
The Mechatronics object model provides capabilities for representing all aspects of
an electromechanical product. In the context of wire harness modeling, Mechatronics
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 Mechatronics object model. This model is depicted in
figure 14-1.
• 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 later in this chapter. You can also find sample programs using
these modules in the \samples\mechatronics directory. For more details about
the modules, see the Integration for Wiring Harness Design Tools manual. For more
details about the module’s functions, see the Integration Toolkit Function Reference
manual.
You can use PLM XML to export and import data used by the Mechatronics API
modules. For more information, see the Integration for Wiring Harness Design Tools
manual or the PLM XML Import Export Administration Help. You can also use the
modules in a Multi-Site Collaboration environment. For more information, see the
Integration for Wiring Harness Design Tools manual or Multi-Site Collaboration
Help.
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 (figure 14-4). You must connect Port1 and Port2 in a
given context.
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.
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);
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);
}
• Target
• Transmitter
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.
There can be multiple redundant signals for a given signal based on the
criticality of the function being regulated.
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.
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
• Configuration and effectivity rules are not supported by GDELine.
Table 14-3 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 manual.
• Gets the processors that are accessed through this gateway processor.
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
stat = ESM_ask_processors_accessedby_processor(
gateway_processor_line, &num_accessed_lines,
&accessed_processor_lines);
stat = ESM_remove_processor_to_processor_association(
gateway_processor_line, num_processor_lines, processorLines,
&hasFailures, &numFailedLines, &failedLines);
15 Traversal Engine
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-2
15 Traversal Engine
This chapter describes the Traversal Engine module that allows you to develop
utilities that traverse Teamcenter Engineering structures, such as Product Structure
(PS), without the requirement to write a specific program.
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
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 Engineering structure such as product structure or folders.
Presently the core module relates to product structure only. The ps_traverse utility,
located in the IMAN_ROOT/bin directory has also been developed to demonstrate
the use of TE.
Basic Features
The features of the Traversal Engine are:
• Represents the Teamcenter Engineering structure as a tree data structure with
each node representing the Teamcenter Engineering object.
• 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 you to store and retrieve a float value with a key as a string, typically
used for summing up functionality.
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 Engineering object that the node
represents.
For information regarding selectors, see the ITK Help. For information on
handlers, see Workflow Help.
Minimum Requirements
You need the following minimum requirements to run the Traversal Engine:
• The Teamcenter Engineering ITK development environment.
Installation
To confirm that you have installed TE successfully, check if the following have been
added to their respective directories:
• The libitk.libraryextension library in the IMAN_ROOT/lib directory.
• 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.
• User interface calls. These write messages to the log file and console and receive
input from the configuration file and the command line arguments.
Sample Implementation
The te_template_itk_main.c file in the IMAN_ROOT/sample/examples directory
demonstrates TE functionality. It can be compiled and studied to understand how
new utilities can be developed.
A Glossary
A Glossary
ACL
See Access Control List (ACL).
Action Handler
Handler used to extend and customize 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 item, item revision, and dataset.
Active Mode
Management of application files in a way that allows their use by both an application
and Teamcenter Engineering. There are two categories of active interaction between
Teamcenter Engineering and an application: Encapsulation and Integration.
Compare with Passive Mode.
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.
AIE
See Application Integration Environment.
AIWS
See Application Interface Web Service.
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.
Alternate
Component that can be used interchangeably within an occurrence, typically for
manufacturing purposes. The preferred alternate is displayed in the structure.
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.
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.
Attribute
Named storage variable that describes an object and is stored with the object. Users
can search the database for objects using the object’s 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 parent 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 Engineering application that enables a system administrator to
define 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 Engineering applications. Users can audit any Teamcenter Engineering
object and event type with an audit definition.
BLOB
Binary large object; attribute type of undefined structure. BLOBs are stored as
binary images within an object.
BOM
Bill of material. See also Design Bill of Material and Manufacturing Bill of Materials.
BOM View
Teamcenter Engineering object used to manage product structure information for
an item.
Business Modeler
Teamcenter Engineering application that enables the system administrator to define
a set of business rules for administering the Teamcenter Engineering data model
behavior. The administrator can change the rules on the Teamcenter Engineering
data model using menus instead of writing code.
BVR
See BOM View Revision (BVR).
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. In the case of data migration,
the Migration Wizard is a client that gathers user input and requests services from
the TDS server. See also Server.
Client Tier
Teamcenter Engineering architectural tier that comprises the Teamcenter
Engineering clients, Teamcenter Engineering integrations with third-party
applications, such as Microsoft Office Integration and Teamcenter 2005 Integration
for AutoCAD, and the third-party applications themselves, such as Microsoft Office
and AutoCAD.
Closure Rule
In PLM XML, a rule that controls the scope of the PLM XML translation of data
imported to and exported from Teamcenter Engineering. Closure rules specify how
the data structure is traversed by specifying the relationships of interest and the
actions to occur when these relationships are encountered.
Component
Objects used to build up an assembly or subassembly.
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 Engineering network. This host
contains the Teamcenter Engineering application root directory, Teamcenter
Engineering data directory, licensing, file managers (Teamcenter File Services and
File Management System), and volumes. For installations that include the Web
tier (four-tier architecture), the corporate server also contains the Teamcenter
Engineering server manager. Multiple application clients can map to or mount the
corporate server.
Dataset
Teamcenter Engineering 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 type object.
Dataset Tool
Teamcenter Engineering object that is the tool used to create or modify a dataset.
Dataset Type
Teamcenter Engineering object that contains a list of tools that can operate on a
dataset.
Derived Default
Default value that depends on a condition (for example, radio = stereo IF car type
= GLX). Compare with Fixed Default.
Effectivity
Identification of the valid use of an aspect of product data tracked by date, event,
unit, or other scheme. You can specify a start definition, end definition, or both for
a particular effectivity.
Effectivity Rule
Rule used to set effective dates on released products and processes with a released
status.
Encapsulation
Active-mode relationship between an application and Teamcenter Engineering in
which the application is brought into the Teamcenter Engineering environment.
Encapsulation allows you to launch the application using a Teamcenter Engineering
dataset object, export data to the application, work in the application, and import
data back into the Teamcenter Engineering database during a session. The import
and export operations between Teamcenter Engineering and the encapsulated
application are executed from within Teamcenter Engineering and the actual
transfer of files is transparent to the user. See also Active Mode and Integration.
Enterprise Tier
Teamcenter Engineering architectural tier that comprises a configurable pool of
Teamcenter Engineering 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 Engineering workspace object that represents a mail message sent by
a Teamcenter Engineering 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.
ESM
See Embedded Software Manager.
Extension
Method or listener implemented for an extension point.
Extension Point
Event or capability in the system, such as a precondition, pre-action, or post-action,
that allow you to implement custom behavior.
Extension Rule
Business rule that defines the customization applied to a particular business
operation through an extension point.
External Extension
Extension created by a user to implement customized behavior.
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.
Filter Rules
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.
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 Product Structure Editor
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 Engineering 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 Engineering. See also Master Form.
Four-Tier Architecture
Teamcenter Engineering architecture that includes four tiers: resource tier, client
tier, Web tier, and enterprise tier.
Four-Tier Deployment
Deployment of the Teamcenter Engineering four-tier architecture. The Web tier,
enterprise tier, resource tier, and client tier can each be hosted on the same or
separate computers.
GDE
See Generic Design Element.
Group
Type of class that does not have a list of attributes associated with it; highest level
in the classification hierarchy.
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.
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 Engineering in
which Teamcenter Engineering is brought into the application. The application
drives Teamcenter Engineering to provide the functionality, such as implicit
checkout when data is modified, and reading and writing data directly from
Teamcenter Engineering 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.
LOV
See List of Values (LOV).
Master Form
Teamcenter Engineering 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 Engineering capability that allows the exchange of data objects among
several Teamcenter Engineering 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 Navigator
Teamcenter Engineering rich client application that is the main access point for
managing product information. My Navigator provides the functionality for creating
objects in the Teamcenter Engineering 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 Navigator window that displays product information as
graphical objects. Although users share product information across the enterprise,
they organize this information individually in personal workspaces.
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.
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.
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 Engineering application that enables a system administrator to create
and manage critical Teamcenter Engineering files and database entries. It is the
point of access for creating a company’s 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
Engineering organization; management of data volumes; and establishment and
maintenance of Teamcenter Engineering 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.
Passive Mode
Management of application files from outside an application. Users do not have
access to Teamcenter Engineering while running the application in passive mode.
Data must be exported (pushed) from Teamcenter Engineering to the application
before it can be worked on and then imported (pulled) into Teamcenter Engineering
after it has been modified. Compare with Active Mode.
Person
Definition containing real-world information about each Teamcenter Engineering
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
UGS 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 Engineering database and read when
a Teamcenter Engineering session is initiated. Preferences allow administrators and
users to configure many aspects of a session, such as user login 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 Engineering rich client.
PSE
See Product Structure Editor.
Pseudo Folder
Special container in Teamcenter Engineering that stores and displays item and
item revision relations in My Navigator.
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 Engineering 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 Engineering 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 Engineering 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 Engineering installed on user workstations.
The rich client accesses Teamcenter Engineering databases using a remote or local
server.
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.
Schema Editor
Teamcenter Engineering application that provides a graphical means for system
administrators to create, modify, and view Teamcenter Engineering database schema
definitions and attributes in Teamcenter Engineering rich client.
Segment
Section of a connection where no intermediate electrical contacts appear.
Sequence Number
Number that identifies individual occurrences (or groups of occurrences) within
a single-level assembly. Components are ordered by sequence number within an
assembly.
Server
System software component that performs a specifically defined set of software
services on behalf of one or more clients. In a typical Teamcenter Engineering
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 Manager
Process that manages a pool of Teamcenter Engineering 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
Engineering 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 (electrical) means of transferring a message from one system to another.
Site
Individual installation of Teamcenter Engineering comprising a single Teamcenter
Engineering database, all users accessing that database, and additional resources
such as hardware, networking capabilities, and third-party software applications
(tools) required to implement Teamcenter Engineering at that site.
Site ID
Unique identifier of a Teamcenter Engineering site. The site ID is used to generate
internal identifiers for Teamcenter Engineering objects that must be unique
throughout an enterprise. Once established, site IDs should not be modified.
Site Name
Unique name of a Teamcenter Engineering site stored in the database as a
user-defined character string.
Site Preference
Teamcenter Engineering preference that applies to the entire site.
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 Product Structure Editor, Manufacturing Structure Editor,
Part Manufacturing Planner, Collaboration Context, and Resource Manager.
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.
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.
System Administrator
Teamcenter Engineering user who is a member of the system administration group.
Task
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.
TCFS
See Teamcenter File Services (TCFS).
Teamcenter Visualization
UGS software suite that provides enterprise-wide product visualization capabilities.
Teamcenter Visualization can be configured for use with both the Teamcenter
Engineering rich client and thin client as a standalone application. Configuring
Teamcenter Visualization for use with the rich client or thin client requires installing
and configuring Teamcenter Engineering Data Integration Services Adapter.
The software suite includes Teamcenter Visualization Base, Teamcenter
Visualization Standard, Teamcenter Visualization Professional, and Teamcenter
Visualization Mockup.
Thin Client
Teamcenter Engineering user interface that provides a streamlined browser-based
view of product information stored in a Teamcenter Engineering database. The
thin client is configured in the Web tier, which creates and serves its Web pages
to the 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.
Type
Teamcenter Engineering application that enables a system administrator to create
and maintain user-defined display names for database object types (item, form,
dataset, tool, alias, folder, status, view, note, unit of measure, relation, and storage
media). An administrator can create multiple user representations that are
identified as belonging to a type of object class in Teamcenter Engineering.
User
Definition that is the mechanism by which Teamcenter Engineering identifies and
interacts with each user. User definitions contain a name (derived from the person
definition), user ID, operating system name, and password.
User Preference
Teamcenter Engineering preference applying to a specific user.
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).
View Type
Attribute of a BOM view revision. The view type specifies the BOM view revision’s
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 Engineering and used to store
the files managed by Teamcenter Engineering. When a user performs an action that
causes Teamcenter Engineering to create a file, the file is created in the Teamcenter
Engineering volume. Users cannot directly access the files in Teamcenter
Engineering volumes; they must do so via a Teamcenter Engineering session.
Web Tier
Teamcenter Engineering 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. The
Web tier application also includes the Application Interface Web Service (AIWS),
WebDAV service, Teamcenter Engineering DIS Adapter, and thin client.
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 Engineering application that enables administrators to graphically
design workflow process templates, incorporating company business practices and
procedures into the templates. Teamcenter Engineering users initiate workflow
processes using these templates.
World
All users regardless of group or role.