Professional Documents
Culture Documents
ENOVIAStudioModelingPlatformMQLGuide V6R2017x
ENOVIAStudioModelingPlatformMQLGuide V6R2017x
MQL Guide
3DEXPERIENCE R2017x
3DEXPERIENCE Platform is based on the V6 Architecture © 2007-2017 Dassault Systèmes.
The 3DEXPERIENCE Platform for 2017x is protected by certain patents, trademarks, copyrights, and other restricted
rights, the full list of which is available at the 3DS support site: http://help.3ds.com/.
Certain portions of the 3DEXPERIENCE Platform R2017x contain elements subject to copyright owned by third party,
the full list of which is also available at the 3DS support site mentioned above.
You will require an account with support in order to view this page. From the support page, select your desired product
version and language to launch the appropriate help. Select Legal Notices from left frame. This displays the full list of
patents, trademarks and copyrights for this product.
Any copyrights not listed belong to their respective copyrights owners.
Table of Contents
Preface ...................................................................................................................... 5
About This Guide .............................................................................................................................. 6
Purpose...................................................................................................................................... 6
Intended Audience ..................................................................................................................... 6
Skills You Need .......................................................................................................................... 6
Introducing 3DSpace ........................................................................................................................ 7
An Information Management System......................................................................................... 7
3DSpace Database Components............................................................................................... 7
Overview of Business Process Services .......................................................................................... 9
Business Process Services Components .................................................................................. 9
Application Components ............................................................................................................ 9
Use of General Client Applications ................................................................................................. 10
Related Documentation .................................................................................................................. 11
Studio Modeling Platform Overview ......................................................................................... 11
MQL Command Reference ...................................................................................................... 11
BPS Administrator Documentation .......................................................................................... 11
App Product Administrator Documentation.............................................................................. 11
Related Documentation Not Installed with BPS or Applications .............................................. 11
How to Use this Guide .................................................................................................................... 13
What To Do Next............................................................................................................................. 14
Table of Contents 1
Using Tcl ......................................................................................................................................... 40
MQL and Tcl ............................................................................................................................. 40
Tcl Syntax Troubleshooting ...................................................................................................... 41
Parameterized MQL Commands.............................................................................................. 43
2 MQL Guide
Working with Saved Structures ................................................................................................ 94
Working with Business Object Files................................................................................................ 96
Checking Out Files................................................................................................................... 96
Handling Large Files ................................................................................................................ 96
Locking and Unlocking a Business Object............................................................................... 97
Modifying the State of a Business Object ....................................................................................... 98
Approve Business Object Command ....................................................................................... 98
Ignore Business Object Command .......................................................................................... 98
Reject Business Object Command .......................................................................................... 99
Unsign Signature ..................................................................................................................... 99
Disable Business Object Command ........................................................................................ 99
Enable Business Object Command ....................................................................................... 100
Override Business Object Command..................................................................................... 101
Promote Business Object Command..................................................................................... 101
Demote Business Object Command...................................................................................... 102
Working with Relationship Instances ............................................................................................ 103
Defining a Connection............................................................................................................ 103
Viewing Connection Definitions ............................................................................................. 104
Table of Contents 3
Defining a Command ............................................................................................................. 124
Using Macros and Expressions in Configurable Components ............................................... 124
Supported Macros and Selects .............................................................................................. 125
Menus ........................................................................................................................................... 127
Creating a Menu..................................................................................................................... 127
Channels....................................................................................................................................... 128
Creating a Channel ................................................................................................................ 128
Portals........................................................................................................................................... 129
Creating a Portal .................................................................................................................... 129
Tables............................................................................................................................................ 130
Creating a Table ..................................................................................................................... 130
Forms............................................................................................................................................ 132
Defining a Form...................................................................................................................... 132
4 MQL Guide
Preface
The Studio Modeling Platform MQL Guide is intended for users who:
• use a command driven interface to all of the functions that can be performed in 3DSpace.
• use MQL to perform most of the operations that can be done using Matrix Navigator or
Business Modeler.
• use MQL to perform other functions of 3DSpace that you can not do with the GUI
applications, including system administration functions.
5
About This Guide
Purpose
This guide provides the MQL programmers with conceptual and reference information concerning
the MQL language.
MQL is the Matrix Query Language. Similar to SQL, MQL consists of a set of commands that help
the administrator set up and test a 3DSpace database quickly and efficiently.
MQL is primarily a tool for building the 3DSpace database. Also, you can use MQL to add
information to the existing database, and extract information from the database.
This guide provides MQL programming concepts to persons responsible for building and
maintaining the 3DSpace database.
Intended Audience
You can use MQL to perform most of the operations that can be done using Matrix Navigator or
Business Modeler. MQL also provides additional commands for functions that can’t be done with
these GUI applications. MQL commands can be run on a command line or via a script. For these
purposes, you can review the introduction and concepts chapters of this guide, or the following
related documentation:
• Matrix Navigator Guide
Review this guide to become familiar with the Matrix application.
• Business Modeler Guide
Review this guide to become familiar with the Business Modeler application, and the kinds of
tasks the Business Administrator performs.
6 MQL Guide
Introducing 3DSpace
7
• MQL - the command line interface tool for executing commands and scripts.
• System Administration - the tool for managing and configuring data and file storage
vaults.
• Business Modeler - the tool for managing the data model and its associated business
processes including types, attributes, relationships, and the web user interface design.
• Matrix Navigator - the tool for searching the data objects based on the data model. This
application is required to administer triggers and other configuration objects.While the
Matrix Navigator is installed as part of Studio Modeling Platform for ease of installation,
this application license is included in both CPF and DTE. For legacy customers that are
still based on thick client deployments vs. Web, the CPF license entitles you to use Matrix
Navigator.
• Studio Federation Toolkit (ADT), which provides documentation and examples for writing
custom programs that use the Adaplet libraries available in 3DSpace. The Studio Federation
Toolkit must be licensed for each Studio Modeling Platform environment that requires
development of custom connectors with the Adaplet APIs.
• File Collaboration Server (FCS), which enables administrators to distribute file data across the
enterprise for optimal upload and download performance. A system license is required for each
physical site that requires remote file storage. There is no limit to the number of users that can
use the File Collaboration Server at a given licensed site, however, all of these users must be
licensed to use 3DSpace, which is the prerequisite.
8 MQL Guide
Overview of Business Process Services
Business Process Services (BPS) is the foundation for all other apps. It includes the schema for all
products, as well as the programs and JavaServer Pages needed to construct the user interface
shared by all the applications. It can also be used as the basis for creating your own applications.
BPS (and the other components and prerequisites) must be installed before you can install any other
apps. Refer to the Business Process Services Installation Guide for details.
Application Components
Each Dassault Systemes product contains the items listed in this table.
Application Components
9
Use of General Client Applications
Some of the instructions in this and other Administration Guides require the use of a general Matrix
client navigator. It is important to restrict the use of these general navigator applications to only a
few specially-trained business administrators.
The general client navigator is the desktop version of Matrix Navigator (also known as the thick
client), including MQL, Matrix, and Business Modeler.
It is important to restrict the use of these general navigator apps to only a few specially-trained
business administrators and to only the purposes described in the Business Process Services - AEF
User Guide and app Administration Guides. Apps run JavaBean code that requires data to have
specific characteristics and conditions. For example, objects may have to have certain relationships
defined, have specific values entered for attributes, be in specific lifecycle states, or be in particular
vaults. When a person works within the app user interface, these data conditions are met. However,
the general Matrix navigators are not necessarily aware of these conditions and therefore a person
working within the general navigators can easily compromise data integrity.
Another reason to restrict access to the general clients is that certain actions have different results
depending on where the action is taken. A command on a JSP page may include options (such as
additional MQL clauses) to ensure that the operation is completed as the application expects, but a
user in a general client has no guidance on what options should be chosen. For example, when a file
is checked into 3DSpace using a general client, the store set in the policy is used; when using an
app to check in a file, the person or company default store is used regardless of the store set by the
policy.
The general navigators must or can be used in situations such as:
• App features require data that cannot be created within the user interface.
For example, some user profile information and template information must be created in a
general navigator.
• Automated business rules and processes need to be configured, such as triggers and
autonamers.
• Data needs to be investigated for troubleshooting, testing, or data conversion.
The general navigators should only be used in these situations, using the instructions provided in
documentation, and only by specially-trained business administrators. Standard users of apps
should never be allowed to work with their data in a general navigator and external customers
should never be given access to a general navigator.
10 MQL Guide
Related Documentation
This section lists the documentation available for BPS and 3DEXPERIENCE apps.
• Studio Modeling Platform Overview
• MQL Command Reference
• BPS Administrator Documentation
• App Product Administrator Documentation
• Related Documentation Not Installed with BPS or Applications
11
For instructions on installing BPS and applications, see the Business Process Services Installation
Guide.
12 MQL Guide
How to Use this Guide
This guide explains the concepts and reference material you need to setup the 3DSpace database
and also to write applications for it. This guide is organized in conceptual chapters and provides
complete syntax and reference information in the latter sections:
• Chapter 1, The MQL Language - Introduces the MQL Language, syntax conventions, scripts,
input modes, commenting, explains how to build an initial database and edit an existing one.
• Chapter 2, Working with Metadata - Provides information about how to define meta data. It
describes attributes, dimensions, types, interfaces, formats, relationships, and policies.
• Chapter 3, Manipulating Data - Explains how to use business objects to manipulate data.
• Chapter 4, Working with Workspace Objects - Explains how to use workspace objects to
manipulate data. It provides information on queries, sets, filters, and cues.
• Chapter 5, Extending an Application - Explains how to use other features in the system to
extend an application such as programs, and applications.
• Chapter 6, Modeling Web Elements- Provides information about commands, menus, tables,
portals, etc.
• Chapter 7, Maintenance - Provides information about how to maintain the system. There are
sections on monitoring clients, system-wide settings, database constraints, diagnostics, etc.
• Chapter 8, Working with Import and Export - Discusses concepts about exporting and
importing administrative and business objects.
Published examples in this document, including but not limited to scripts, programs, and related
items, are intended to provide some assistance to customers by example. They are for
demonstration purposes only. It does not imply an obligation for Dassault Systemes to provide
examples for every published platform, or for every potential permutation of platforms/products/
versions/etc.
13
What To Do Next
Start by understanding the basic concepts explained in the chapters of this guide and then use the
reference as a tool when programming in MQL. The reference section will provide complete syntax
and description of all the parameters, clauses, and grammar of MQL commands.
You can also use MQL within Java or .Net programs when using the MQL Command package of
the Studio Customization Toolkit. Before you begin programming for 3DSpace, you should review
the following information:
• 3DSpace Installation Guide
The 3DSpace Service must be installed before installing Studio Customization Toolkit.
Information on installing the server is included in the this guide.
Always refer to the current Program Directory for any changes that have been made since the
publication of this manual.
14 MQL Guide
1
The MQL Language
This chapter introduces the MQL command language in the following sections:
• About MQL
• Accessing MQL
• Using Commands and Scripts
• Building an Initial Database
• Modifying an Existing Database
• Working with Transactions
• Working With Threads
• Using Tcl
15
About MQL
The Matrix Query Language (MQL) is similar to SQL. MQL consists of a set of commands that
help the administrator set up, build, and test a 3DSpace database quickly and efficiently.
You can also use MQL to add information to the existing database, and extract information.
MQL acts an interpreter for 3DSpace and can be used in one of three modes:
1. Interactive Mode - which means executing each command from the command line.This mode
is typically used when you have only a few modifications to make or tests to perform.
2. Script Mode - which means using scripts to run commands. This lets you combine commands
and also have a repeatable history of commands. You should use MQL scripts as long as you
are in the building process. Later, you may decide to add information and files into 3DSpace.
When adding information you may require additional MQL commands. Rather than entering
them interactively, you can create a new script to handle the new modifications.
3. Tool Command Language (Tcl) Mode - which means you can use the tcl/tk scripting language.
With Tcl embedded in MQL, common programming features such as variables, flow control,
condition testing, and procedures are available.
After the database is built, you will most likely maintain it through the Business Modeler interface
which helps you see what you are changing.
16 MQL Guide
Using Control Characters
All editing commands are control characters which are entered by holding the Ctrl or Esc key while
typing another key, as listed in the following table. All editing commands operate from any place
on the line, not just at the beginning of the line.
Command Line Editing Control Characters
Ctrl-K Kills from the cursor to the end of the line (see Ctrl-Y).
Ctrl-R Begins a reverse incremental search through the history list. Each
printing character typed adds to the search substring (which is
empty initially). MQL finds and displays the first matching
location. Typing Ctrl-R again marks the current starting location
and begins a new search for the current substring.
Type Ctrl-H Or press the Del key to delete the last character from the search
string. MQL restarts the search from the last starting location.
Repeated Ctrl-H or Del characters, therefore, unwind the search to
the match nearest to the point where you last typed Ctrl-R or
Ctrl-S (described below).Type Esc or any other editing character
to accept the current match and terminate the search.
Type Ctrl-H Or press the Del key until the search string is empty to reset the
start of the search to the beginning of the history list. Type Esc or
any other editing character to accept the current match and
terminate the search.
Ctrl-S Begins a forward incremental search through the history list. The
behavior is like Ctrl-R but in the opposite direction through the
history list.
Ctrl-T Transposes the current and previous character.
Ctrl-Y Yanks the previously killed text back at the current location.
18 MQL Guide
Using Tcl/Tk Mode
Tcl Overview
Tcl (tool command language) is a universal scripting language that offers a component approach to
application development. Its interpreter is a library of C procedures that have been incorporated
into MQL.
With Tcl embedded in MQL, common programming features such as variables, flow control,
condition testing, and procedures are available for use. The Tk toolkit is also included. Tcl and Tk
are widely available and documented. The information in this section is simply an overview of
functionality. For more detailed procedures, consult the references listed in the section.
Tcl enhances MQL by adding the following functionality:
• Simple text language with enhanced script capabilities such as condition clauses
• Library package for embedding other application programs
• Simple syntax (similar to sh, C, and Lisp):
Here are some examples of using tcl
Command Output
set a 47 47
Substitutions:
Command Output
set b $a 47
Quoting:
Command Output
20 MQL Guide
Accessing MQL
There are several ways to access the MQL from the operating system.
For example, if you are working on a PC, select the icon.
Or
If you are working on a UNIX platform, enter the MQL command using the following syntax:
mql [options] [-] [file...]
Brackets [] indicate optional information. Do not include the brackets when you enter the
command. Braces {} may also appear in a command syntax indicating that the items in the braces
may appear one or more times.
When the system processes the mql command, the command interface starts up in one of two
modes: interactive or script. The mode it uses is determined by the presence of the hyphen and file
name(s):
Interactive mode is used when the command includes the hyphen and/or does not include a file
name(s). For example, to run MQL interactively, enter either:
mql -
Or:
mql
In both of these commands, no files are specified so the interpreter starts up in an interactive mode
to await input from the assigned input device (usually your terminal).
Each MQL command and command option is discussed in the reference section.
• FILENAME is the name of the file to be created.
• DBUSER is the name used to connect to the database. This is the database user that is created
to hold the database. It is established by the database administrator.
• DBPASSWORD is the security password associated with the Username. This is established by
the database administrator. The user password is encrypted as well as encoded.
• CONNECTSTRING For Oracle, the connect string is the Oracle “connect identifier”, which
can be a net service name, database service name, alias or net service alias. For SQL Server, it
is the name of the ODBC datasource.
• DRIVER is one of the following depending on which database you use:
• Oracle/OCI80
• CLI
• MSSQL/ODBC
22 MQL Guide
Using Commands and Scripts
All commands perform an action within 3DSpace. For example, actions might define new
structures within the database, manipulate the existing structures, or insert or modify data
associated with the database structures.
An MQL script is an external file that contains MQL commands (see the
example below). You can create this file using any text editor. After
you insert all the desired MQL commands, you can batch process them by
specifying the name of the script file in the mql command.
###########################################################
# Script file: SampleScript.mql
# These MQL commands define a vault and create an object.
###########################################################
verbose on;
#
# Set context to Matrix System Administrator’s and define a new vault.
#
set context dba;
add vault "Electrical Parts";
output "Electrical Parts vault has been added"
#
# Set context to that of person Steve in vault "Electrical
Subassemblies"
#
set context vault "Electrical Subassemblies" user Steve;
#
# Add a business object of type Drawing with name C234 A3
# and revision 0 and check in the file drawing.cad
#
output "now adding a business object for Steve";
add businessobject Drawing "C234 A3" 0
policy Drawing
description "Drawing of motor for Vehicle V7";
checkin businessobject Drawing "C234 A3" 0 drawing.cad;
#
quit;
Values Are separated within clauses by a comma (,). Values may be single or, if the
keyword accepts a list of values, they can be specified either separately or in a
list. For example:
attribute Size
attribute Length
Comments Begin with a pound sign (#) and end with a carriage return. For example:
# list users defined within the database
Comments are ignored by 3DSpace and are used for your information only.
24 MQL Guide
MQL Command Conventions
When commands are displayed on your screen, the commands are displayed in diagrams which
obey a set of syntax rules. These rules are summarized in the following table:
[option] Optional items are contained within square brackets [ ]. You are not required to enter the clause or value
if you do not need it.
Do not include the brackets when you are entering an option.
{option} All items contained within braces { } can appear zero or more times.
Do not include the braces when you are entering an option.
|option1| All items shown stacked between vertical lines are options of which you must choose one.
|option2|
|option3|
Eventually, you will probably want help only on a selected MQL category:
application association attribute
26 MQL Guide
set context [ITEM {ITEM}];
where ITEM is:
| person PERSON_NAME |
| password [PASSWORD_VALUE] |
| vault [VAULT_NAME] |
print context;
This information indicates that there are two commands associated with the context category: the
set context and print context commands.
The first command has three clauses associated with it: the person, password, and vault clauses.
The square brackets ([]) on either side of PASSWORD_VALUE mean that it is optional. If a clause
is used, you must obey the syntax of the clause. In the person clause, the syntax indicates that a
value for PERSON_NAME is required. Words shown in all uppercase indicate user-defined values.
(Refer to Entering (Writing) MQL Commands for a complete description of syntax rules.)
For example, if you are processing large blocks of commands, you may want to
precede or end each block with an Output command. This enables you to monitor
the progress of the script.
password PASSWORD; The Password command enables you to change the current context password.
The Password command enables you to change your own password (which can
also be done with the Context command).
run FILE_NAME [continue]; The Run command enables you to run a script file. This is useful if you are
working in interactive mode and want to run a script.
The continue keyword allows the script to run without stopping when an error
occurs. This is essentially the same as running MQL with the -k option, but it is
available at run time, making it usable by programs.
shell COMMAND; The Shell command enables you to execute a command in the operating system.
For example, you can perform an action such as automatically sending an
announcement to a manager after a set of changes are made.
The Output command (see above) sends a message to your output device; but, it
cannot send a message to a different device. You can do so with the Shell
command.
verbose [on|off]; The Verbose command enables you to increase or decrease the amount of message
detail generated by the MQL interpreter as the script is processed. This is similar
to the -v Option. For more information, see MQL Command Reference: mql
Command in the online user assistance.
When set to ON, more detail is provided. When set to OFF, only errors and
important system messages are displayed.
version; The Version command enables you to see which version of MQL you are using.
For example, this is useful if you want a record of the version used to process a
script.
Using Comments
Comments visually divide scripts into manageable sections and remind you of why structures and
objects were defined and modified. Comments, which are preceded in the script by a pound sign
(#), are ignored by MQL:
# script comments
Each comment line must begin with a pound sign (#).
28 MQL Guide
Parameterized MQL Commands
Using parameterized MQL prevents MQL injection flaws in apps. An MQL injection attack
consists of insertion or “injection” of an MQL command via the input data from the client to the
application. A successful MQL injection exploit can read sensitive data from the database, modify
database data (e.g., through Insert/Update/Delete commands), execute administration operations on
the system (e.g., Clear Vault command), and in some cases, issue commands to the operating
system.
The following Java example is unsafe because it allows an attacker to inject code into the command
that the system would execute:
String command = "temp query bus Part * * where owner == " +
request.getParameter("customerName");
mql.executeCommand(context, command);
If "customerName" is equal to "; clear all", then the "temp query" will fail because the
command is incomplete, but the "clear all" command will execute as a valid command.
MQL injection flaws are introduced when software developers create dynamic commands that
include user-supplied input. Avoiding MQL injection flaws is straightforward. Developers should
either stop writing dynamic commands, or prevent user-supplied input that contains malicious
MQL from affecting the logic of the executed command.
In support of this, the Open Web Application Security Project (OWASP) recommends that software
developers apply the following defenses to prevent MQL injection attacks:
• Use prepared statements (parameterized commands).
• Use stored procedures.
• Escape all user-supplied input.
• Enforce "least privilege" (e.g., by minimizing the privilege of user accounts). See Least
Privilege, below.
• Perform "white list input validation" (e.g., by providing a list of the available inputs, such as
attribute ranges). See White List Input Validation, below.
The Server already provided capabilities to implement stored procedures (Java Program Objects or
JPOs), enforce "least privilege" (P&O security) and to perform "white list input validation"
(attribute ranges). Additionally, web application development teams use APIs that allow them to
encode and escape data.
You can use parameterized MQL commands to first to define the MQL command and then pass in
each parameter to the command at a later time. This coding style makes it possible to distinguish
between code and data, regardless of what user data is supplied.
Escaping of user-supplied input is unnecessary in MQL. In other words, for code that read:
where "type" was bracketed by two single quotes, now rather than writing:
For details on how to implement parameterized MQL commands, see the Javadoc online help for
the matrix::db::MQLCommand::executeCommand() method.
When passing a multi-value argument, you must pass in multiple parameters for that argument. For
example, for an MQL command that contains:
...value1,value2,value3...
the MQLCommand.executeCommand must define:
Format: ...$n,$n+1,$n+2,...
Values: "value1", "value2", "value3", …
For example, this command defines a multi-value attribute:
mql.executeCommand(ctx, "mod bus $1 $2 $3,$4", boID1, "str_att", "str1", "str2");
30 MQL Guide
Building an Initial Database
Building a database usually involves writing two scripts. One script will contain all the definitions
used by the database. The second script creates business objects, associates files with the objects,
and defines relationships between objects.
By separating these two steps, it is easier to test the database. You cannot create business objects or
manipulate them until the definitions are in place. By first creating and testing all the definitions,
you can see if the database is ready to add objects. You may want to alter the definitions based on
test objects and then use the altered definitions for processing the bulk of the object-related data.
Do not attempt to add the persons creator, guest, or Test Everything using MQL. Adding or
modifying these objects could cause triggers, programs or other application functions not to work.
The clear all command should NEVER be used while users are on-line.
Clearing Vaults
To test and build new vaults, use the Clear Vault command. This command ensures that the vault
does not contain any business objects. It can be run by a person with System Administrator
privileges.
clear vault VAULT_NAME;
The clear vault should NEVER be used while users are on-line.
Definition Order
1 Roles You can define roles, groups, and persons either way
Groups depending on your application. Since associations are
Persons combinations of groups and roles, they must be created
Associations after groups and roles are defined.
Or:
Persons
Groups
Roles
Associations
2 Attributes Order is important for this set of definitions. For example,
Types types use attributes, so attributes must be defined before
Relationships types.
Formats
Stores
Policies
3 Vaults Vaults can be defined at any time although they are most
commonly defined last.
32 MQL Guide
Modifying an Existing Database
After you define the initial database, you may want to modify it to add additional users and
business objects. If the number of users or the amount of information is large, you should consider
writing a MQL script. This enables you to use a text editor for editing convenience and provides a
written record of all of the MQL commands that were processed.
Often when you are adding new business objects, you will define new vaults to contain them. This
modular approach makes it easier to build and test. While some new definitions may be required, it
is possible that you will use many of the existing definitions. This usually means that the bulk of
the modification script will involve defining objects, manipulating them, and assigning
relationships. These actions are done within the context of the vault in which the objects are placed.
To test and build new vaults, use the Clear Vault command. This command ensures that the vault
does not contain any business objects. See Clearing the Database for details.
When writing your script for modifying an existing database, remember to include comments,
occasional output commands, and a Quit command at the end (unless you’ll want to use the
interactive MQL interpreter after script completion).
A transaction involves accessing the database or producing a change in the database. All MQL
commands involve transactions.
Implicit Transactions
When you enter an MQL command, the transaction is started and, if the command is valid, the
transaction is committed (completed). For example, assume you enter the following MQL
command:
add person Debbie;
As soon as you enter the command, the system starts the transaction to define a person named
Debbie. If that person is already defined, the command is invalid and the transaction aborts—the
command is not processed and the database remains unchanged. If the person is not already
defined, the app is committed to (the completion of) the transaction to add a new person. Once a
transaction is committed, the command is fully processed and it cannot be undone. In this case,
Debbie would be added to the database.
Ordinarily, starting, committing, and aborting transactions is handled implicitly with every MQL
command. Each command has two implied boundaries: the starting keyword at the beginning of the
command and the semicolon or double carriage return at the end. When you enter an MQL
command, a transaction is implicitly started at the keyword and is either committed or aborted
depending on whether the content of the command is valid.
This implicit transaction control can also be performed explicitly.
These commands enable you to extend the transaction boundaries to include more than one MQL
command.
• If you are starting a transaction, use the read option if you are only reading.
• Without any argument, the start transaction command allows reading and modifying
the database.
34 MQL Guide
an error message, particularly if you are entering the commands interactively when typing errors
are common.
Let’s look at an example in which you want to create a set of business objects and then associate a
collection of files with those objects. You might successfully create the objects and then discover
that you cannot place the files in them. With normal script or interactive MQL processing, the
objects are created even though the checkin fails. By altering the transaction boundaries, you can
tie the successful processing of the files to the creation of the business objects to contain them. For
example:
start transaction update;
add businessobject Drawing “C234 A3” 0
policy Drawing
description “Drawing of motor for Vehicle V7”;
checkin businessobject Drawing “C234 A3” 0 V7-234.MTR;
add businessobject Drawing ”C234a A3” 0
policy Drawing
description “Drawing of alt. motor for Vehicle V7”;
checkin businessobject Drawing ”C234a A3” 0 V7-234a.MTR;
commit transaction;
This transaction is started and the current state of the database is saved. The add
businessobject commands create business objects, and the checkin businessobject
commands add the files.
When the commit transaction command is processed, MQL examines all the commands
that it processed since the start transaction command. If no error messages are detected,
all changes made by the commands are permanently made to the database.
If ANY errors are detected, NONE of the changes are committed. Instead, the system returns the
database to the recorded state it was in at the start of the transaction. This essentially gives you an
all or nothing situation in the processing of MQL commands. However, savepoints can be set in the
transaction to be used in conjunction with the abort transaction command, which can save
some of the work already done.
The set transaction savepoint [NAME] command allows you to set a point within a
transaction that will be used for any required rollbacks. You cannot set a transaction savepoint
when you have an open Iterator.
If you specify the NAME in an abort transaction command, the transaction is rolled back to
the state where the savepoint was created. If no name is specified, the entire transaction is rolled
back. Of course the transaction must still be committed before the commands between the start
transaction and the savepoint are processed. The set transaction savepoint
NAME command can be issued multiple times without error. The effect is that the savepoint is
changed from the original savepoint state in the transaction to the current state of the transaction.
The abort transaction NAME command can also be issued multiple times.
If set transaction savepoint NAME is issued and the transaction has already been
marked as aborting, the command will fail and return an error. When using this command via
Studio Customization Toolkit or Tcl, be sure to check for the returned error "Warning: #1500023:
Transaction aborted". If you assume set transaction savepoint NAME works, a
subsequent abort transaction NAME may roll the transaction back to an older state than
expected.
The wait and nowait arguments are used to tell the system if you want to queue up for locked
objects or not. When nowait is used, an error is generated if a requested object is in use. The
default is to wait; the wait keyword is a toggle.
One advantage to using the transaction commands to process command blocks involves the
processing time. Commands processed within extended transaction boundaries are processed more
quickly than the normal command transactions.
If you choose to process blocks of MQL commands within explicit transaction boundaries, you
need to carefully consider the size and scope of the commands within that transaction. When you
access anything with an MQL command, that resource is locked until the transaction is completed.
Therefore, the more commands you include within the transaction boundaries, the more resources
that will be locked. Since a locked resource cannot be accessed by any other user, this can create
problems if the resource is locked at a time when heavy use is normal. The use of large transactions
may also require you to adjust the size of your Oracle rollback segments. See your Oracle
documentation for more details.
You should immediately attend to an explicit transaction that either has errored or is awaiting a
commit or abort command. Many database resources other than objects are also locked with the
pending transactions. Users will begin to experience lock timeouts as they attempt typical database
operations.
36 MQL Guide
start trans;
set context user PERS1;
mod bus ACCESS a1 0 int-u 2;
# Now switch back to creator and modify the group so that PERS1 can
modify
# >>>>> OR make this change from a separate MQL/Business session.
set context user creator;
mod person PERS1 assign group GRP1;
# CASE 1: Try to modify - this is not allowed
set context user PERS1;
mod bus ACCESS a1 0 int-u 2;
commit trans;
# Now switch back to creator and modify object to kick it out of cache
set context user creator;
mod bus ACCESS a1 0 int-u 3;
# Modify the group so that PERS1 can modify
mod person PERS1 assign group GRP1;
# Start a transaction and get the object in PERS1's cache with
successful mod
start trans;
set context user PERS1;
mod bus ACCESS a1 0 int-u 4;
# Now switch back to creator and modify the group so that PERS1 can NOT
modify
# >>>>> OR make this change from a separate MQL/Business session.
set context user creator;
mod person PERS1 remove assign group GRP1;
Transaction Triggers
You can configure a transaction trigger that will be invoked one time for all events on a type or
relationship at the end of a transaction. When defined on a type or relationship, whenever a
business object or connection of that type or relationship is modified, at the end of the outside
transaction, the program associated with the transaction trigger is invoked.
If both a transaction trigger and a general modify trigger are defined for a type, both triggers will be
invoked at the end of the outside transaction. Transaction triggers can only be Action triggers; and
cannot be configured as a Check or Override trigger.
The programs associated with transaction triggers must be JPOs. In addition, these programs will
always run as deferred. If configured to run immediately, that setting is ignored and program
execution is still deferred. Because the program is deferred, if any errors occur during the program
execution, all prior changes within the transaction boundary are not rolled back. In addition, the
trigger program should not trigger another transaction event on the same business object or
connection; if it does, an error will be thrown.
Transaction trigger JPOs are not invoked for objects that are deleted inside a transaction.
checkout
38 MQL Guide
Working With Threads
MQL has a notion of a “thread,” where you can run multiple MQL sessions inside a single process.
Each thread is like a separate MQL session, except that all threads run within the same MQL
process. This concept was introduced into MQL to support the MSM idea of multiple “deferred
commit” windows.
For more information, see MQL Command Reference: thread Command in the online user
assistance.
For a description of common Tcl syntax errors, see Tcl Syntax Troubleshooting.
The Tcl command, exit, returns you to native MQL. Like the MQL Quit command, Exit can be
followed by an integer value which is passed and interpreted as the return code of the program.
40 MQL Guide
tcl;
set a "one\\two\\three"
puts "a contains $a"
puts "b will use slashes instead of backslashes"
regsub -all {\\} $a {/} b
puts "now b contains $b"
puts "now b contains $b"
Run this file from MQL (or alternatively type each line in MQL command window). The final line
of output will be:
now b contains one/two/three
This is consistent with how the same lines of code behave in native Tcl.
However if you use this same code as a MQL program object, to get the same output you need to
use triple rather than double backslashes so your code becomes:
tcl;
set a "one\\\two\\\three"
puts "a contains $a"
puts "b will use slashes instead of backslashes"
regsub -all {\\\} $a {/} b
42 MQL Guide
Parameterized MQL Commands
Using parameterized MQL prevents MQL injection flaws in apps. An MQL injection attack
consists of insertion or "injection" of an MQL command via the input data from the client to the
application. A successful MQL injection exploit can read sensitive data from the database, modify
database data (e.g., through Insert/Update/Delete commands), execute administration operations on
the system (e.g., Clear Vault command), and in some cases, issue commands to the operating
system.
The following Java example is unsafe because it allows an attacker to inject code into the command
that the system would execute:
String command = "temp query bus Part * * where owner == " +
request.getParameter("customerName");
mql.executeCommand(context, command);
If "customerName" is equal to "; clear all", then the "temp query" will fail because the
command is incomplete, but the "clear all" command will execute as a valid command.
MQL injection flaws are introduced when software developers create dynamic commands that
include user-supplied input. Avoiding MQL injection flaws is straightforward. Developers should
either stop writing dynamic commands, or prevent user-supplied input that contains malicious
MQL from affecting the logic of the executed command.
In support of this, the Open Web Application Security Project (OWASP) recommends that software
developers apply the following defenses to prevent MQL injection attacks:
• Use prepared statements (parameterized commands).
• Use stored procedures.
• Escape all user-supplied input.
• Enforce "least privilege" (e.g., by minimizing the privilege of user accounts). See Least
Privilege, below.
• Perform "white list input validation" (e.g., by providing a list of the available inputs, such as
attribute ranges). See White List Input Validation, below.
The Server already provided capabilities to implement stored procedures (Java Program Objects or
JPOs), enforce "least privilege" (P&O security) and to perform "white list input validation"
(attribute ranges). Additionally, web application development teams use APIs that allow them to
encode and escape data. Release V6R2013 adds the ability to use parameterized MQL commands.
Parameterized MQL commands allow the developer first to define the MQL command and then to
pass in each parameter to the command at a later time. This coding style makes it possible to
distinguish between code and data, regardless of what user data is supplied.
Parameterized commands ensure that an attacker is not able to change the intent of a query, even if
the MQL commands are inserted by the attacker. In the following safe example, if an attacker were
to enter a userID of tom' or '1'='1, the parameterized query would not be vulnerable and
would instead look for a username that literally matches the entire string tom' or '1'='1.
String customerName = request.getParameter("customerName");
String whereClause = "'owner == " + customerName + "'";
String command = "temp query bus $1 $2 $3 where $4";
mql.executeCommand(context, command, "Part", "*", "*",
whereClause);
For details on how to implement parameterized MQL commands, see the Javadoc online help for
the matrix::db::MQLCommand::executeCommand() method.
44 MQL Guide
2
Working with Metadata
In this section:
• Attributes
• Dimensions
• Interfaces
• Types
• Formats
• Policies
• Relationships
• Rules
• Ownership
45
Attributes
An attribute is any characteristic that can be assigned to an object or relationship. Objects can have
attributes such as size, shape, weight, color, materials, age, texture, and so on.
You must be a Business Administrator to add or modify attributes. (Refer also to the Business
Modeler Guide.)
Defining an Attribute
Before types and relationships can be created, the attributes they contain must be defined as
follows:
add attribute NAME [ADD_ITEM {ADD_ITEM}];
46 MQL Guide
Assigning Attribute Types
The Type clause is always required. It identifies the type of values the attribute will have. An
attribute can assume one of these types of values: binary, string, Boolean, real, integer, date,
shortbinary, and enum. Shortbinary attributes contain internal IDs and enum attributes contain
range values. When determining the attribute type, you can narrow the choices by deciding if the
value is a number or a character string. Once a type is assigned to an attribute, it cannot be changed.
The user can associate only values of that type with the attribute.
the data for this attribute has already been converted and you should not continue (type N).
After applying a dimension, you can only change the default units of measure before any user
enters any data for the attribute. After values are stored in the as entered field, you cannot change
the default units of measure.
48 MQL Guide
b ) Change the multiplier to the appropriate value.
c ) Change the offset to the appropriate value.
d ) Click Edit in the Units section.
5. Click Edit at the bottom of the dialog box.
Attribute Names
A fully qualified name includes both the object name and the attribute name, using the format
ADMIN.ATTRIBUTE. An unqualified name includes the attribute name only. The only time the
fully qualified name of an attribute is used is when select attribute is specified. Otherwise,
the display name is always the unqualified attribute name. This enables multiple attributes to have
the same name, because if the names are displayed "fully qualified," (i.e., T1.a1), they do not
appear as having the same name.
No matter how the selectable is written (attribute[X] where x = I1.a1, I2.a1, a1, etc.), the
returned attribute is always the simple/common attribute name. The correct value is always
returned if you select using the fully qualified local attribute name (ADMIN.ATTRIBUTE, for
example, T1.a1). For example:
MQL<219>print bus tp1 test2 1 select attribute[i1.*];
business object tp1 test2 1
attribute[i1.a1] = 3DPLM
MQL<220>print bus tp1 test2 1 select attribute[].value;
business object tp1 test2 1
attribute[tp1.a1].value = 3DPLM
attribute[a1].value = geo
attribute[i1.a1].value = 3DPLM
MQL<221>print bus tp1 test2 1 select attribute[a1];
business object tp1 test2 1
50 MQL Guide
attribute[tp1.a1] = 3DPLM
attribute[i1.a1] = 3DPLM
attribute[a1] = geo
One limitation of this feature is that there is no way to select only local attributes. For example,
specifying attribute[*.a1] returns an error:
MQL<55>print bus T1 test 0 select attribute[*.a1];
Error: #1900068: print business object failed
Error: #1500063: Unknown field name ’attribute[*.a1]’
However, you can use '*' to match all global and local attributes matching a pattern, for example:
MQL<4>add type k1;
MQL<5>add interface k1 type k1;
MQL<6>add attribute ak1 type string owner interface k1;
MQL<7>add interface k2 type k1;
MQL<8>add attribute ak1 type string owner interface k2;
MQL<9>add attribute ak1 type string;
MQL<10>mod type k1 add attribute ak1;
MQL<11>add bus k1 test 0 vault unit1 policy simple-u;
MQL<12>mod bus k1 test 0 add interface k1 add interface k1 add
interface k2;
MQL<13>print bus k1 test 0 select attribute [*k1];
business object k1 test 0
attribute[k2.ak1] =
attribute[ak1] =
attribute[k1.ak1] =
Using Patterns for Attribute Names in Temp Query Bus Where clause
When a pattern is provided for an attribute name in a temp query bus’ where clause, the
pattern is resolved against all attributes, not just attributes available for specific objects. This can
result in unsupported criteria when using local attributes. For example, in a database with attributes
of different derivations of names beginning with 't', the following occurs:
MQL<43>add attr t3 type integer;
MQL<44>add attr t4 type string;
MQL<45>list attr t*;
t3
t4
MQL<46>add type typ1 attr t4;
MQL<47>add policy pol1 type typ1 state s1;
MQL<48>add bus typ1 aaa 1 policy pol1 vault v1 t4 abc;
MQL<49>temp query bus typ1 * * where 'attribute[t*] ~~ "*b*"';
Warning: #1500802: Different attribute types are found in expanded
attribute list
By default, attributes are single-value. It is not allowed to specify default values for multi-value
attributes. Import and export can handle multi-value attribute definitions and instances.
The lxString table indexes have been changed as follows:
• The index on lxType, lxVal, lxOid is now only LxType, lxVal. In addition, the index order is
lxType, lxVal on all databases.
• The unique index on lxOid, lxType includes the non-key column lxVal on SQL Server.
For more information, see MQL Command Reference: attribute Command in the online user
assistance.
Range-Value Attributes
While multi-value attributes allow you to enter distinct values, range-value attributes allow you to
enter maximum and minimum values (for example, to model a range of 100%-20%). This
capability is enabled for numeric fields as well as dates (for example, to model a start and end date).
MQL provides the following support for range-value attributes:
• Range-value attributes can be applied to numeric and date attributes.
• Dimension can also be applied to the numeric fields.
• The range can have only one UOM value.
52 MQL Guide
• Searching is performed against both values.
• When setting values for a range-value attribute, you can specify either endpoint as inclusive
(by default), exclusive (using the keywords minexclude and maxeclude), or open-ended (if no
value is specified).
You define an attribute as having a range by specifying its type as rangevalue at the time of
creation. Only numeric and date attribute types can be defined as range-value attributes. If you
attempt to define a string or boolean attribute type as rangevalue, an error will be thrown.
To define an attribute as specifying a range of values, use the command:
add attribute NAME rangevalue;
By default, attributes do not specify a range of values. It is not allowed to specify default values for
range-value attributes. Import and export can handle range-value attribute definitions and
instances.
For more information, see MQL Command Reference: attribute Command in the online user
assistance.
Only existing singlevalue attributes can be modified to become multivalue. If the attribute
is already a rangevalue, an error will be thrown.
If there are instances of a singlevalue attribute in the database, the modification moves all
instances from the existing attribute tables to the new multi-/range-value attribute tables in the
database.
If an attribute is already multivalue and has multiple values (instances), changing it to
singlevalue is not allowed and will cause an error to be thrown. For example, you can use
either of the following commands to change a multivalue attribute to singlevalue:
modify attribute NAME notmultivalue;
modify attribute NAME !multivalue;
The above is OK if the attribute is already either multivalue or rangevalue and instances exist.
The above is OK if the attribute is not already multivalue. In other words, if it is a singlevalue
attribute with no instances, then this is permitted.
modify attribute NAME notrangevalue;
modify attribute NAME !rangevalue;
Modification Allowed?
singlevalue (without any instances) -> rangevalue Yes
singlevalue (with instances) -> rangevalue No
singlevalue (without any instances) -> multivalue Yes
singlevalue (with instances) -> multivalue Yes
rangevalue (without any instances) -> singlevalue Yes
rangevalue (with instances) -> singlevalue No
rangevalue (without any instances) -> multivalue No
rangevalue (with instances) -> multivalue No
multivalue (without any instances) -> singlevalue Yes
multivalue (with instances) -> singlevalue Yes (as long as there is only one
value for each instance)
multivalue (without any instances) -> rangevalue No
multivalue (with instances) -> rangevalue No
If the values themselves have spaces or commas, then they must be passed in single or double
quotes using one of the following methods:
mod bus T N R ATTR_NAME ’foo bar1’,’foo bar2’,’foo bar3’;
mod bus T N R ATTR_NAME "foo bar1","foo bar2","foo bar3";
Attempting to provide a comma-separated list of values for an attribute that is not multi-value will
cause an error to be thrown.
For range-value attributes, the keywords minexclude and maxexclude indicate that the range
endpoints do not include the minimum and maximum values, respectively. This is similar to
interval notation in algebra.
54 MQL Guide
Range-value attributes can have the following possible values:
Values Description
minval::maxval • Both minval and maxval are included for any query
For example: operation. In the example, it considers the value of
the range from 5 to 10 (i.e., including 5 and 10).
5::10
• The selectables includeminval and
includemaxval both return TRUE.
minval::maxval minexclude • Only maxval is included for any query operation. In
For example: the example, it considers the value of the range from
6 to 10 (excluding 5).
5::10 minexclude
• The selectable includeminval returns FALSE.
minval::maxval minexclude maxexclude • Both minval and maxval are excluded for any query
For example: operation. In the example, it considers the value of
the range from 6 to 9 (excluding 5 and 10).
5::10 minexclude maxexclude
• The selectables includeminval and
includemaxval both return FALSE.
::maxval [|maxexclude] • The value of the range is considered from the
For example: negative system limit for integer or float values
(e.g., from -2,147,483,648 to +10).
::10
• The selectable openminval returns TRUE.
minval:: [|minexclude] • The value of the range is considered from minval up
For example: to the positive system limit for integer or float
values.
5::
• The selectable openmaxval returns TRUE.
If a business object has to set a range-value attribute to have open-ended minimum and maximum
values, then one of the values does not need to be provided.
The following table shows some examples of adding/modifying range-value attributes for a
business object.
add bus T N R intattr 1::3 The attribute intattr is stored in the database
minexclude maxexclude; as two separate table rows with values 1 and 3,
and orders 1 and 2, respectively.
add bus T N R intattr ::3; The minval is open in this case.
add bus T N R intattr 3::; The maxval is open in this case.
mod bus T N R intattr add 4::5; Multiple values are not allowed for range-value
attributes. Since the attribute already has a range
of 1::3, attempting to add a second range will
throw an error.
mod bus T N R intattr 4::5; This range will replace the existing range value
of 1::3 with the range value of 4::5.
The above command removes the value 3 from the multi-value attribute on the business object. If
there are multiple rows with the same value, then all of those rows are removed.
A multi-value attribute can have more than one instance of the same value. The command
add bus T N R intattr 1,2,3,1; will create four separate rows in the database table.
add bus T N R intattr 1,2,3; Attribute values 1,2,3 are added in that
order.
mod bus T N R intattr add 4 order 2; Attribute value 4 is inserted in the
third position, so that the values are
1,2,4,3.
mod bus T N R intattr add 8; Attribute value 8 is added in the last
position, so that the values become
1,2,4,3,8.
mod bus T N R intattr remove 4; The value 4 is removed from the
attribute. If there are several instance
of the same value, all are removed.
mod bus T N R intattr remove order 2; The value in the third position is
removed.
mod bus T N R intattr replace 5 order 2; The current value in the third position
is replaced with the value 5.
mod bus T N R intattr 7; The attribute value 7 replaces all other
values, and the attribute value for the
object becomes only 7.
56 MQL Guide
Querying a Business Object for Multi-Value or Range-Value Attributes
Printing a business object returns multiple values for a multi-value attribute, in ascending order. For
example, if there exists a type T1 with an integer multi-value attribute M1 and there is one object of
this type, printing this object produces the following results:
add bus T1 test 0 policy P1 M1 1,2,3;
print bus T N R select attribute[M1].value;
attribute[M1].value = 1
attribute[M1].value = 2
attribute[M1].value = 3
There is no selectable that can retrieve all of the values of a multi-value attribute as a single string.
For range-value attributes, the existing value selectable returns two values, as shown below:
add bus T1 test 0 policy P1 M1 1::3;
print bus T N R select attribute[M1].value;
attribute[M1].value = 1
attribute[M1].value = 3
The minval and maxval selectables for business objects print the minimum and maximum values,
respectively, of range-value attributes. For example:
print bus T N R select Returns the minimum value of a range-value
attribute[NAME].minval; attribute. Returns nothing for multi-value and
single-value attributes.
Using the minval and maxval selectables in query Where clauses may have performance issues.
It is recommended not to use either of these selectables as part of Where clauses.
Given a business object with a multi-value attribute M1 created with the command:
add bus T1 test 0 policy P1 M1 "1","2","3";
The following table lists the outputs produced by various queries of this business object:
Query Returns:
The results from greater-than '>' and less-than '<' operators for range-value attributes are
interpreted such that the entire range for the attribute should be '>' or '<' the literal.
The following table lists the outputs produced by various queries of this business object:
Query Returns:
Given a business object with a multi-value attribute M1 created with the commands:
add bus T1 test 0 policy P1 M1 1,2,3;
add bus T1 test2 0 policy P1 M1 4,5,6;
add bus T1 test3 0 policy P1 M1 7,2,3;
The following table lists the outputs produced by various queries of this business object:
Query Returns:
58 MQL Guide
Given a business object with a multi-value attribute M1 created with the commands:
add bus T1 test 0 policy P1 M1str val1,val2,val3;
add bus T1 test2 0 policy P1 M1 val4,val5,val6;
add bus T1 test3 0 policy P1 M1str Val1,val2,val3;
The following table lists the outputs produced by various queries of this business object:
Query Returns:
In the case of multi-value attributes, using ".value" in the Where clause (e.g., where
attribute[M1].value == 'val1') is less efficient than without (e.g., where
attribute[M1] == 'val1'). This is because the Where clause condition is resolved by means
of a precise select statement, and when ".value" is not used, evaluation is done in memory, which is
more intensive. It is, therefore, advisable to construct Where clauses without ".value".
Since the attribute M1 has three values, the above add bus statement should see three separate
entries for the UOM values in the unit table and three corresponding values in the attribute table in
the database. The entries in the two tables are tied together with the order number.
The following attribute selectables return multiple values, all of which are output based on the
order number:
attribute.inputvalue;
attribute.inputunit;
attribute.dbvalue;
attribute.dbunit;
attribute.unitvalue;
60 MQL Guide
attribute.generic;
For range-value attributes, there is just one UOM value for the entire range in the unit table.
For a range-value attribute, the range is specified. An example of a history entry would be:
history = modify - user: creator time: Fri Jul 20, 2012 11:00:54 AM
EDT state: s1 attr: 20::30 was 10::20
62 MQL Guide
Dimensions
The dimension administrative object provides the ability to associate units of measure with an
attribute, and then convert displayed values among any of the units defined for that dimension. For
example, a dimension of Length could have units of centimeter, millimeter, meter, inch and foot
defined. Dimensions are used only with attributes. For more information, see MQL Command
Reference: attribute Command: Add Attribute Command: Dimension Clause in the online user
assistance.
The definition of the units for a dimension includes determining which unit will be the default (the
normalized unit for the dimension), and the conversion formulas from that default to the other
units. The conversion formulas are based on a multiplier and offset entered when the unit is
defined. The normalized unit has a multiplier of 1 and an offset of 0.
To convert to the normalized value stored in the database to a different unit, the system uses this
formula:
normalized value = unit value * multiplier + offset
To display a value in units other than the normalized units, the system uses this formula:
unit value = (normalized value - offset) / multiplier
Only the normalized value is stored in the database. When an application requires the value for an
attribute to be displayed, the system converts the normalized value to the units required. The value
can be entered in any supported unit of the dimension, but it will be converted and stored in the
default units.
Real attribute normalized values are stored with the same precision as real attribute values with no
dimension applied. See Attributes for more information. To avoid round-off errors with integer
attributes, the default units should be the smallest unit (for example, millimeters rather than
centimeters or meters).
The conversion process affects the precision. In general, up to 12 digits of precision can be
assumed. For each order of magnitude that the offset and the converted value differ, another digit
of precision is lost.
Dimensions help qualify attributes that quantify an object. For example, for a type with an attribute
Weight, the user needs to know if the value should be in pounds or kilograms, or another dimension
of weight. When the attribute definition includes a dimension, the user is provided with that
information in the user interface. In addition, the user has the ability to choose the units of the
dimension to enter values.
When applying dimensions to attributes that already belong to business object instantiations, refer
to Applying a Dimension to an Existing Attribute for information on converting the existing values
to the required normalized value.
Defining a Dimension
Before attributes can be defined with a dimension, the dimension must be created. You can define a
dimension if you are a business administrator with Attribute access, using the add dimension
command:
add dimension NAME [ADD_ITEM {ADD_ITEM} ];
If you wanted to normalize the dimension on Celsius, you would enter these values when defining
the units:
For dimension definitions that are to be applied to an integer, all multiplier and offset values in the
dimension should be whole numbers, and the “smallest” unit should be the default.
64 MQL Guide
Interfaces
You may want to organize data under more than one classification type. For instance, a Part may
have a classification based on its function, which is most typical, but it may also require
classification on other issues such as production process, manufacturing location, etc. For each
classification type, there is typically a collection of attributes that can be defined for each instance
of the classification type and used for searching.
An Interface is a group of attributes that can be added to business objects as well as connections to
provide additional classification capabilities. When an Interface is created, it is linked to
(previously-defined) attributes that logically go together. Interfaces are defined by the Business
Administrator and are added to business object or relationship instances.
An Interface can be derived from other Interfaces, similar to how Types can be derived. Derived
Interfaces include the attributes of their parents, as well as any other attributes associated with it
directly. The types or relationships associated with the parents are also associated with the child.
The primary reason to add an interface to a business object or a connection is to add the attributes to
the instance that were not defined on the type. Moreover, when you add an interface to a business
object or a connection, it gives you the ability to classify it by virtue of the interface hierarchy.
Attribute values that come from interfaces cannot be used in a create access rule, because the
interfaces are not applied until AFTER the create access checks.
Defining an interface
An object interface is created with the Add Interface command:
add interface NAME [ADD_ITEM {ADD_ITEM}];
A type identifies a kind of business object and the collection of attributes that characterize it. When
a type is created, it is linked to the (previously defined) attributes that characterize it. It may also
have methods and/or triggers associated (refer to Programs and the Configuration Guide:
Triggers). Types are defined by the Business Administrator and are used by users to create business
object instances.
A type can be derived from another type. This signifies that the derived type is of the same kind as
its parent. For example, a Book is a kind of Publication which in turn is a kind of Document. In this
case, there may be several other types of Publications such as Newspaper, Periodical, and
Magazine.
This arrangement of derived types is called a type hierarchy. Derived types share characteristics
with their parent and siblings. This is called attribute inheritance. When creating a derived type,
other attributes, methods, and triggers can be associated with it, in addition to the inherited ones.
For example, all Periodicals may have the attribute of Page Count. This attribute is shared by all
Publications and perhaps by all Documents. In addition, Periodicals, Newspapers, and Magazines
might have the attribute Publication Frequency.
You must be a Business Administrator to add or modify types. (Refer also to your Business Modeler
Guide.)
Type Characteristics
Inherited Properties
Types can inherit properties from other types:
• Abstract types act as categories for other types.
Abstract types are not used to create any actual instances of the type. They are useful only in
defining characteristics that are inherited by other object types. For example, you could create
an abstract type called Income Tax Form. Two other abstract types, State Tax Form and Federal
Tax Form, inherit from Income Tax Form.
66 MQL Guide
• Non-abstract types are used to create instances of business objects.
With non-abstract types, you can create instances of the type. For example, assume that
Federal Individual Tax Form is a non-abstract type. You can create business objects that
contain the actual income tax forms for various individuals. One object might be for a person
named Joe Smith and another one for Mary Jones. Both objects have the same type and
characteristics although the contents are different based on the individuals.
Defining a Type
An object type is created with the Add Type command:
add type NAME [ADD_ITEM {ADD_ITEM}];
A format definition is used to capture information about different application file formats. A format
stores the name of the application, the product version, and the suffix (extension) used to identify
files. It may also contain the commands necessary to automatically launch the application and load
the relevant files from Collaboration and Approvals. Formats are the definitions used to link
Collaboration and Approvals to the other applications in the users’ environment.
Applications typically change their internal file format occasionally. Eventually older file formats
are no longer readable by the current version of the software. It is wise to create new format
definitions (with appropriate names) as the applications change so that you can later find the files
that are in the old format and bring them up to date.
The system does not do any checking of the type of file that is checked into a format. For example,
a word document with a .doc extension can be checked into a format defined for HTML files. This
means that formats can be used to define directories for the checked in files of a business object.
A business object can have many file formats and they are linked to the appropriate type definition
by the policy definition (see Policies).
Defining a Format
Format definitions are created using the MQL Add Format command. This command has the
syntax:
add format NAME [ADD_ITEM {ADD_ITEM}]
68 MQL Guide
Policies
A policy controls a business object. It specifies the rules that govern access, approvals, lifecycle,
revisioning, and more. If there is any question as to what you can do with a business object, it is
most likely answered by looking at the object’s policy.
You must be a Business Administrator to add or modify policies. (Refer also to your Business
Modeler Guide.)
A policy is composed of two major sections: the first describes the general behavior of the
governed objects and the second describes the lifecycle of the objects.
General Behavior
The first section controls the creation of the object and provides general information about the
policy. This information includes:
• The types of objects the policy will govern.
• The types of formats that are allowed.
• The default format automatically assigned.
• Where and how checked in files are managed.
• How revisions will be labeled.
Lifecycle
The second section provides information about the lifecycle of the objects governed by the policy.
A lifecycle consists of a series of connected states, each of which represents a stage in the life of the
governed objects. Depending on the type of object involved, the lifecycle might contain only one
state or many states. The purpose of the lifecycle is to define:
• The current state of the object.
• Who will have access to the object.
• The type of access allowed.
• Whether or not the object can be revised.y
• Whether or not files within the object can be revised.
• The conditions required for changing state.
• Whether or not the state has been published. See “Published States” on page 71.
A policy can exist without any states defined. This is enabled mainly to support legacy data. There
are certain disadvantages to not defining any states:
• It is not possible to have access control without any state definition.
• Some operations, like disabling checkout history, cannot be performed since no state exists to
control this.
If a policy is created without state, a warning is displayed stating "Policy has no STATE defined."
State Description
Initial Preparation The building site is evaluated and prepared by the site excavator and
builder. After the site is reviewed and all preparations are completed, the
excavator and builder sign off on it and the site enters the second state,
Framing.
Framing Carpenters complete the framing of the house and it is evaluated by the
builder, architect, and customer. In this state, you may want to prohibit
object editing so that only viewing is allowed. If the framing is complete
to the satisfaction of the builder, architect, and customer, it is promoted
to the third state, Wiring.
Wiring The electrician wires the house. However, the electrician may sign off on
the job as completed only to have the builder reject it. When approval is
rejected, promotion to the next state is prevented from taking place.
As the house progresses through the building states, different persons would be involved in
deciding whether or not the object is ready for the next state.
When determining how many states an object should have, you must know:
• What are the states in an object’s life.
• Who requires access to the object.
• What type of access they need.
Once a policy is defined, you can alter it even after business object instances are created that are
governed by it.
70 MQL Guide
• Owner—refers to the specific person who is the current owner of the object instance. When an
object is initially created in the database, the person who created it is identified as the owner of
the object. This person remains the owner unless ownership is transferred to someone else.
• User—refers to a specific person, group, role, or association who will have access to the
object. You can include or exclude selected groupings or individuals when defining who will
have access.
For additional information on access privileges, including which access takes precedence over the
other, see Studio Modeling Platform Overview: Controlling Access in the online user assistance.
Published States
Every state has a published flag. In policies where this flag is turned on, a best-so-far (BSF) flag is
automatically propagated to business objects that enter such states. By default, the published flag is
turned off. A migration tool is available to migrate policies, both to incorporate the new published
flag and to update all business objects governed by policies that have the flag turned on in order to
set the published flag correctly. See the Database Migration Guide, available in the Program
Directory, for details on the migration tool.
To determine whether the published flag has been set on an object, you can use:
print policy NAME select state.published;
To retrieve the boolean value of the published flag as it is propagated to business objects, use:
print bus T N R select.current.published;
Policies allow definition of two revision sequences, major and minor. You can define a revision
sequence for a policy as follows:
add policy NAME majorsequence A,B,C,... minorsequence 1,2,3
delimiter '-';
If both major and minor sequences are defined, then a delimiter is required. The delimiter is used to
concatenate major and minor revision strings for storage in the database, so it must be an ASCII
non-alphanumeric character that could never be part of a major/minor revision string calculated
from the two sequences.
The Modify Policy command allows you to edit either sequence, but not to change the delimiter or
add/remove either sequence, as this would make major/minor revision strings impossible to parse.
You can use the Transition Revisions command to add a second sequence to a policy that only one
(see the Database Migration Guide for details).
The Print Policy command also allows the corresponding selectables, such as:
print policy NAME select majorsequence minorsequence delimiter;
Policy and state access definitions have the following access flags:
• minorrevise is synonymous with the earlier revise flag, and is used to control the Revise Minor
command for adding a new minor revision.
• majorrevise is used to control the Revise Major command for adding a new major revision.
The following events support type definitions:
• minorrevision is synonymous with the earlier revision keyword, used for defining triggers on a
type.
• majorrevision has been added as a new event for defining triggers on a type.
Minorrevision and majorrevision are values that are derived from the revision field using the policy
delimiter. Object uniqueness that incorporates revision information must include both minor and
major revision fields. The revision keyword should be used to define such a uniquekey. Therefore,
minorrevision and majorrevision are not supported as fields for unique keys.
These capabilities in policy definition have corresponding pieces of data and selectables for
business objects.
You can mark any state in a policy to indicate whether it is allowed to create a major/minor revision
of an object in that state as follows:
mod policy NAME state STATE minorrevision TRUE|FALSE
majorrevision TRUE|FALSE;
72 MQL Guide
The terms "minorrevise" and "revise" are synonymous when defining access rules in policy and in
the print bus select current.access[minorrevise] command. However, as output from
the Print Policy command (e.g., print policy select state and print bus select
current.access), the earlier "revise" keyword continues to be used for forward compatibility.
Likewise, the keyword "revisioned" continues to be used to mark minorrevise events in history.
Input Keywords
In the following cases, "revise" and "revision" have the same meaning as long as the object’s policy
supports ONLY minor revisioning. If, however, the governing policy supports both major and
minor revisions, there is a difference:
• print bus T N R select revision prints the full revision string of the object. If the
policy supports both minor and major revisions, this will be major-minor.
• print bus T N R select revisions prints the full revision string for all objects in the
object’s minor revision sequence.
• copy/mod bus T N R name NEWNAME revision NEWREV: NEWREV uses the full revision
string (major-minor) as specified in the governing policy.
In an access rule filter:
• A filter-including expression of the form current.access[ACCESS_TYPE] == TRUE
accepts either minorrevise or revise as the ACCESS_TYPE.
• A filter-including expression of the form current.access ~~ *ACCESS_TYPE* is risky
since revise is now be a substring of both minorrevise and majorrevise (but see Output
Keywords below).
Output Keywords
In various places, the kernel outputs the keywords revise/revision or populates macros with such a
string. Changing such output could break any application code that depends on the current ’revise/
revision’ keyword. Although it would be cleaner and more consistent to migrate these outputs to
minorrevise/minorrevision, the current output has been retained to satisfy forward compatibility.
• print bus T N R select current.access maintains ‘revise’ as the keyword describing
minor revise access (e.g., current.access == read,modify,revise,show).
• The $ACCESS macro can be used in an access rule filter and is populated with the current
access being checked whenever the filter is evaluated (e.g., the following rule allows a
different condition for modify vs. revise access):
($ACCESS == modify && <modify-condition>) || ($ACCESS == revise &&
<revise-condition>)
This continues to be populated as ‘revise’.
• The EVENT macro continues to be populated as ‘Revision’ to pass to revision triggers.
• History records still say history = revisioned - user: creator ….
To remove the Frozen state, you need to block the transition from Create to Frozen and from Frozen
to Released, and remove the signature ToCreate. You would use these commands to accomplish
this:
modify policy POLICYNAME state Create block Frozen;
modify policy POLICYNAME state Frozen block Released;
modify policy POLICYNAME state Create remove signature ToCreate;
The result would look like this:
To add a state back in that was previously removed, you would use these commands:
modify policy POLICYNAME state Create unblock Frozen;
modify policy POLICYNAME state Frozen unblock Released;
To add the signature back in, you need to define the signature requirements for that transition. For
more information, see MQL Command Reference: policy Command: Modifying Signature
Requirements in the online user assistance.
74 MQL Guide
NAME is the name you assign to the policy.
ITEM is an Add Policy clause which defines information such as the types of objects governed by
the policy, the types of formats permitted by the policy, the labeling sequence for revisions, the
storage location for files governed by the policy, and the states and conditions that make up an
object’s lifecycle.
For more information, see MQL Command Reference: policy Command in the online user
assistance.
A relationship definition is used along with the policy to implement business practices. Therefore,
they are relatively complex definitions, usually requiring planning.
For example, in manufacturing, a component may be contained in several different assemblies or
subassemblies in varying quantities. If the component is later redesigned, the older design may then
become obsolete. Component objects could be connected to the various assembly and subassembly
objects that contain it. Each time objects are connected with this relationship, the user could be
prompted for the quantity value for the relationship instance. If the component is later redesigned,
the older design may become obsolete. When a revision of the component object is then created,
the relationship would disconnect from the original and connect to the newer revision. If the
component is cloned because a similar component is available, the cloned component may or may
not be part of the assembly the original component connects to. The connection to the original
should remain but there should be no connection to the cloned component.
For the process to work in this fashion, the relationship definition would include the attribute
“quantity.” The cardinality would be “many to many” since components could be connected to
several assemblies and assemblies can contain many components. The revision rule would be
“float” so new revisions would use the connections of the original. The clone rule would be “none”
so the original connection remains but no connection is created for the clone.
A relationship can be derived from another relationship. This signifies that the derived relationship
is of the same kind as its parent. This arrangement of derived relationships is called a relationship
hierarchy. Derived relationships share characteristics with their parent and siblings. This is called
relationship inheritance. When creating a derived relationship, other attributes, methods, and
triggers can be associated with it, in addition to the inherited ones.
You must be a Business Administrator to define relationships. (Refer also to your Business Modeler
Guide.) Relationships are typically initially created through MQL when all other primary
administrative objects are defined. However, if a new relationship must be added, it can be created
with Business Administrator.
76 MQL Guide
• What is the cardinality for the relationship at the to end? Should a business object be allowed
to be on the to end of only one or many of this type of relationship?
• When a business object at the from end of the relationship is revised or cloned, a new business
object (similar to the original) is created. What should happen to this relationship when this
occurs? The choices for revisions and clones are: none, replicate, and float.
Should the relationship stay on the original and not automatically be connected to the new
revision or clone? If so, pick none.
Should the relationship stay on the original and automatically connect to the new revision or
clone? If so, pick replicate.
Should the relationship disconnect from the original and automatically connect to the new
revision or clone? If so, pick float.
• When a business object at the to end of the relationship is revised or cloned, a new business
object (similar to the original) is created. What should happen to this relationship when this
occurs? The choices are the same as for the from end.
• What attributes, if any, belong on the relationship? Quantity, Units, and Effectivity are
examples of attributes which logically belong on a relationship between an assembly and a
component rather than on the assembly or component business object. Each instance, or use of
the relationship, will have its own values for these attributes which apply to the relationship
between the unique business objects it connects.
Use a table like the one below to collect the information needed for relationship definitions.
Dynamic Relationships
To support major/minor revisioning of business objects, "dynamic" relationships have a pointer to a
MajorId representing a minor revision family rather than an individual business object. The TO end
of a dynamic relationship resolves to a specific business object by identifying the best-so-far (BSF)
object within the minor revision family.
The dynamic relationship feature adds an additional requirement for database definition with
Oracle installations: the Oracle user (i.e., database) must have CREATE VIEW privileges. Run the
following command to add this privilege:
SQL> grant connect, resource, create view to USER:
Grant succeeded.
SQL> commit;
Commit complete.
where USER is the V6 Oracle user.
For more information, see MQL Command Reference: relationship Command: Add Relationship:
Dynamic Clause in the online user assistance.
MQL Export/Import
Policies are exported/imported with added fields.
Business object export/import is not supported on objects governed by policies with
majorsequence set.
Dynamic relationships are not exported with business objects.
Defining a Relationship
A relationship between two business objects is defined with the Add Relationship command:
add relationship NAME [ADD_ITEM {ADD_ITEM}];
78 MQL Guide
For more information, see MQL Command Reference: relationship Command in the online user
assistance.
Use rules to limit user access to attributes, forms, programs, and relationships. Unlike policies,
rules control access to these administrative objects regardless of the object type or state. For
example, a policy might allow all users in the Engineering group to modify the properties of Design
Specification objects when the objects are in the Planning state. But you could create a rule to
prevent those users from changing a particular attribute of Design Specifications, such as the Due
Date. In such a case, Engineering group users would be unable to modify the Due Date attribute, no
matter what type of object the attribute is attached to. For a explanation of how rules work with
other objects that control access, see Studio Modeling Platform Overview: Access Precedence in
the online user assistance.
When you create a rule, you define access using the three general categories used for assigning
access in policies: public, owner, and user (specific person, group, role, or association). For a
description of these categories, see Studio Modeling Platform Overview: Controlling Access: User
Access: User Categories and Hierarchies in the online user assistance.
You can also include keys in rules to specify multiple access definitions for the same user. For more
information, see Studio Modeling Platform Overview: Controlling Access: User Access: Security
Context Access in Policies and Rules in the online user assistance.
For complete information about creating rules, see MQL Command Reference: rule Command in
the online user assistance.
Creating a Rule
Rules are defined using the Add Rule command:
add rule NAME [ADD_ITEM {ADD_ITEM}];
80 MQL Guide
Ownership
Business objects and relationships can have multiple owners. In addition, several objects may need
to have a common baseline access level. This section describes how ownership of business objects
and relationships functions, including multiple ownerships and ownership inheritance.
Multiple Ownerships
There are many cases where a business object or relationship may require multiple ownerships,
such as a part that has multiple RDO, RMO, and RSO security attributes, each of which represent
an organization or project owner. It is possible to specify multiple ownerships for an object. A
complete ownership definition includes the following:
• Organization—a "role" object that represents an organization
• Project—a "role" object that represents a project
• Comment—a short string used primarily for annotation
• Access—a comma-separate list of security tokens
Each of these fields can be specified when providing an ownership. The first three fields (org,
project, and comment) together provide a unique identifier for the ownership entry.
You can add ownerships to or subtract them from an existing business object or relationship.
Ownership information is used to determine object access rights dynamically. Commands that are
used to get or set the single organization/project ownership on business objects continue to
function, but generate an error if more than one ownership is present.
For more information, see MQL Command Reference: businessobect Command: Modify Business
Object: Adding or Removing Business Object Ownerships and MQL Command Reference:
relationship Command: Modify Relationship: Adding or Removing Relationship Ownerships in the
online user assistance.
Ownership Inheritance
Rather than maintaining security on a per-object basis, it is possible to govern a list of objects
where the entire collection of objects has a common baseline access level by aggregating
ownerships based on another object. This allows an object to inherit the ownership list from another
object as its baseline access in addition to having its own direct ownership. Thus, it is no longer
necessary to manage ownership by adding or subtracting ownerships individually on each object in
a workspace since ownership for an object comprises an embedded reference to a parent object.
Existing applications that store parent information as a relationship (e.g., workspace) must add an
ownership definition in addition to the relationship. Applications that currently lack a parent or
folder notation can create the parent ownership entry without creating a new relationship entity by
specifying a parent object. The access rule engine dynamically extends an entity’s ownership list to
include the (non-inherited) ownerships of the parent.
To do this, you specify an object ID and another optional comment relating to the parent object.
Ownerships, constructed in this form implement ownership inheritance from the parent. The access
rule engine dynamically extends an entity's ownership list to include the ownerships of the parent.
These inherited ownerships include all ownerships added to the entity using the multiple-ownership
feature. The ownerships do not include the parent’s primary ownership identified in the parent’s
organization and project basic properties. You can use ownership inheritance on multiple levels.
82 MQL Guide
Inheritance Rules
Use inheritance rules to define ownership or access details that can be assigned to an object on the
to or from end of a relationship when a connection is made based on the criteria defined in the rule.
For example, if you add a document to a folder, you can define an inheritance rule to add access to
that document. If the document is removed from the folder, any access granted by the inheritance
rule is removed from the document.
When defining an inheritance rule, you specify a relationship and whether the ownership or access
operates on the object at the from or to end of the relationship. Include clauses in the rule, based on
object types and policies, that define when this inheritance rule should be applied.
To define the from and to criteria for an inheritance rule, specify the object type and policy type.
You can specify all for the type or policy. For example:
add inheritancerule SoftwareRule operateson to appliesto
ProductRelationship ownership SoftwareOwnerRI from type Part,Product
policy all to type "Software Product" policy "Software Development" as
show,read
In this example:
• SoftwareRule is the name of the inheritance rule
• operateson to defines which end of the relationship the specified ownership or access will
be applies (in could also be operateson from)
• appliesto ProductStructure defines the relationship that when used to connect two
objects, the system checks the criteria for from and to below to determine if this inheritance
rule should be applied
• ownership defines ownership inheritance (you can also define access inheritance)
• SoftwareOwnerRI defines the name of this rule item (an inheritance rule can contain
multiple rule items)
• from type Part,Product policy all defines the from side of a relationship
• to type "Software Product" policy "Software Development"defines the to side
of a relationship
• as show,read defines the specific accesses granted by this rule
The interpretation of the above inheritance rule is that whenever an app uses the ProductStructure
relationship to connect an object of type Part or Product being governed by any policy to an object
of type Software Product being governed by the Software Development policy, then the shown
access (show,read) is added to the ownership of the Software Product (the to side of the relationship
as defined by operateson).
When the app determines that the criteria for an inheritance rule have been met, it adds a comment
to the business object (as defined by the operateson and from or to clauses) in this format:
enorule_<rel_pid>_<tenant_id>_<rule_id>_<rule_item_id>
Where:
• enorule is the prefix that represents auto-generated inheritance
• rel_pid is the physical id of the connection object
• tenant_id is the tenant id
• rule_id is the inheritance rule id
• rule_item_id is the id of the specific rule item within the inheritance rule
84 MQL Guide
3
Manipulating Data
This chapter explains how to create and use business objects to manipulate data.
In this section:
• Creating and Modifying Business Objects
• Making Connections Between Business Objects
• Working with Business Object Files
• Modifying the State of a Business Object
• Working with Relationship Instances
85
Creating and Modifying Business Objects
Business objects form the body of Collaboration and Approvals. They contain much of the
information an organization needs to control. Each object is derived from its previously-defined
type and governed by its policy. Therefore, before users can create business objects, the Business
Administrator must create definitions for the types (for more information, see Types in Chapter 2)
and policies (for more information, see Policies in Chapter 2) that will be used. In addition, the
users (persons, groups, and roles) must be defined before they can have access to the application
(for more information, see Studio Modeling Platform Overview: Controlling Access: User Access
in the online user assistance).
When creating a business object, the first step is to define (name) the object and assign an
appropriate description and attribute values for it. File(s) can then be checked into the object and it
can be manipulated by establishing relationships, moving it from state to state and perhaps deleting
or archiving it when it is no longer needed. This chapter describes the basic definition of the object
and its attributes. In the next chapter, relationships, connections, states, checking files in and out,
and locking objects are described in more detail.
Each element must appear in the order shown. If any element is missing or if the values are given in
the wrong order, the business object specification is invalid.
You can also optionally specify the vault in which the business object is held. When the vault is
specified in this manner, only the named vault needs to be checked to locate the business object.
This option can improve performance for very large databases.
TYPE NAME REVISION [in VAULT]|ID [in VAULT]
See Defining a Business Object later in this chapter for more information about additional
elements.
The full business object specification includes TYPE NAME REV: the type from which the object
was created, the object name—the user-supplied identifier that is associated with the definition and
identifies the object to the end user(s)—and the revision.
In the sections that follow, each of the three required elements is discussed and sample values are
given.
86 MQL Guide
Business Object Type
The first element in a business object specification is the object’s type. Every object must have a
type associated with it. When you specify the object’s type, remember that it must already be
defined.
If the type name you give in the business object specification is not found, an error message will
display. If this occurs, use the List Type command (for more information, see MQL Command
Reference: list admintype Command in the online user assistance) to check for the presence and
spelling of the type name. Names are case-sensitive and must be spelled using the same mixture of
uppercase and lowercase letters.
When you are assigning a type to a business object, note that all types have attributes associated
with them. These attributes appear as fields when the object is accessed in Matrix Navigator. These
fields can then be filled in with specific values or viewed for important information.
For example, you might assign a type of “Metallic Component” to an object you are creating. With
this type, you might have four attributes: type of metal, size, weight, and strength. If you use an
Attribute clause in the add businessobject command or modify the attributes, you can insert
values that will appear whenever the object is accessed. If attributes are not specified when a
business object is added or modified, the attribute defaults (if any) are used.
Use: the first * for the unknown type, the HC* for the name beginning with “HC”, and the third *
for the unknown revision level. The result would be all the objects beginning with “HC”.
Product HC-430 A
Product HC-470 B
The first specification has no revision designator and must be specified as such. This might be
because Component types cannot be revised under the governing policy. It might also be because
this is the original object that uses a sequence where the first object has no designator.
For more information, see MQL Command Reference: policy Command: Add Policy: Sequence
Clause in the online user assistance.
Object ID
When business objects are created, they are given an internal ID. As an alternative to TYPE NAME
REV, you can use this ID when indicating the business object to be acted upon. The ID of an object
can be obtained by using the print businessobject selectable “ID”. Refer to Viewing Business Object
Definitions later in this chapter for more information on select commands.
88 MQL Guide
should also have the actual date/time of the creation and/or modification of the legacy data, and not
the system generated date and time (that would reflect when the data was migrated).
In some cases, you may want the business objects to act as a placeholder, representing the actual
objects in the external system that is constantly changing. You can update the business objects on a
regular basis by resetting the current state as well as the start, end and duration values of the states.
Modifying a business object this way avoids the need for promoting the object through the
lifecycle, which would result in each state reflecting the date of the import/promotion and not the
date from the legacy system. Each of these (current state, start date, end date, and duration) can be
changed independently, with no effect on each other. If you want to maintain these values to be
consistent with each other, you must change them all. There is no impact on the lifecycle of these
objects if these values are not kept consistent, except for queries or webreports that depend on these
values.
For more information, see MQL Command Reference: businessobject Command: Add Business
Object: Adding Legacy Data in the online user assistance.
The kernel does not in itself prevent concurrent modifications. Applications using the kernel can
use the reservation data to implement ways to warn or disallow users from modifying a reserved
object.
When an object or connection is reserved, the kernel adds the “reserved” tag which includes a user
and a timestamp. An application can be programmed such that it checks for the reserved status of a
business object or connection, and if reserved, can issue a warning or disallow other users from
modifying the business object or connection until it is unreserved.
For example:
print businessobject “Box Design” “Thomas” “A” select reserved
reservedby reservedstart reservedcomment;
90 MQL Guide
revise businessobject and copy businessobject commands. For more
information, see MQL Command Reference: businessobject Command in the online user assistance.
Not all business objects can be revised. If revisions are allowed, the Policy definition may specify
the scheme for labeling revisions. This scheme can include letters, numbers, or enumerated values.
Therefore you can have revisions with labels such as AA, 31, or “1st Rev.”
If the REVISION_NAME is omitted, 3DSpace automatically assigns a designator based on the next
value in the sequence specified in the object’s policy. If there is no sequence defined, an error
message results.
If there is no defined revision sequence or if you decide to skip one or more of a sequence’s
designators, you can manually specify the desired designator as the REVISION_NAME.
Creating new revisions has several side affects. When appending to a revision sequence with the
MQL command, these behaviors are handled as described below:
Major/Minor Revisions
Business objects have two levels of revisioning, minor and major:
• Minor revisions are individual business objects. The Revise Minor command creates a minor
revision family as a linear, ordered sequence of objects with a minor revision string that is
incremented for each new minor revision.
• Major revisions are equivalent to complete minor revisions. The Revise Major command
begins a new major revision (minor revision family) by creating the first minor revision in the
new family. An incremented major revision string is generated for each new major revision.
You can create as many new major revisions as you want by invoking Revise Major multiple
times.
A new UUID called "majorid" is assigned to all objects in a major revision (all objects in the same
minor revision family).
The collection of all objects created from an original object using the Revise Major/Minor
commands comprises a larger family called a Version Family. A new UUID called VersionId is
assigned to all objects in the version family.
92 MQL Guide
The following figure shows an example of the result of a sequence of major and minor revision
operations on an object. The orange arrows indicate Revise Minor operations, while the blue
arrows indicate Revise Major operations.
The top row of objects shows a version family (enclosed in the dark blue dashed box) comprising
four major revisions (i.e., minor revision families enclosed in orange dashed boxes). The four
major revisions contain two, three, two, and one minor revisions, respectively.
The second row shows another version family with a single major revision containing three minor
revisions. This version family was created through "evolution," or by a Copy operation that copies
the logical ID.
The third row shows another version family with a single major revision containing one minor
revision. This family was created through a New From operation that did not copy the logical ID.
Validation of MajorID/VersionID during Object Creation
Error checking of majorid/versionid is performed when a business object is added. More
specifically, when performing create/clone business object operations (e.g., with the Add Bus
command), if the specified majorid or versionid is already associated with other objects in the
database, an error is generated. This applies only to Add Bus, not Copy or Revise.
add businessobject TYPE NAME REVISION policy POLICY_NAME [ITEM {ITEM}];
…
<< std::endl << " where ITEM is:"
<< std::endl << " | description VALUE |"
…
<< std::endl << " | physicalid UUID |"
<< std::endl << " | logicalid UUID |"
<< std::endl << " | versionid UUID majorid UUID |"
<< std::endl << " | majororder VALUE |"
<< std::endl << " | minororder VALUE |"
…
As described in Relationships in Chapter 2, relationship types are created which can be used to link
business objects. A relationship type is specified when making a connection or an instance of that
relationship type between two business objects. One business object is labeled as the TO end and
one is labeled as the FROM end. When the objects are equivalent, it does not matter which object is
assigned to which end. However, in hierarchical relationships, it does matter. 3DSpace uses the TO
and FROM labels to determine the direction of the relationship.
The direction you select makes a difference when you examine or dissolve connections. When you
examine an object’s connections, you can specify whether or not you want to see objects that lead
to or away from the chosen object. When you disconnect objects, you must know which object
belongs where. Therefore, you should always refer to the relationship definition when working
with connections.
Connections are also used to make associations between files, folders, and modules in DesignSync
and business objects in Collaboration and Approvals, if you are using DesignSync stores for source
control. These types of connections are generally made in apps which use MQL commands in
implementation. For more information, see the Business Process Services - Common User Guide:
About DesignSync File Access.
For more information about the commands that make and break connections between business
objects, see MQL Command Reference: businessobject Command in the online user assistance. For
more information about other commands that can be used to make connections, see Relationships
in Chapter 2.
list structure;
The print structure command displays the results in the same manner as expand bus
does. For example, after executing the above command (which outputs the data to the MQL
94 MQL Guide
window, as well as saving it as a structure), you could execute the following to generate the output
again:
print structure “Assigned Parts”;
Within the print structure command you can also use select clauses on either the business object or
the relationship as well as use the output/dump or terse clauses.
The copy structure command lets you copy structures to and from any kind of user.
Including overwrite will replace the copied structure with any structure of the same name that
was in the to user’s workspace.
If an object has been disconnected or deleted, it is no longer listed as part of the structure. On the
other hand, if other objects were connected since the structure was saved, they would not
automatically appear in the output of the print structure command. Another expand command
would need to be executed with the structure clause to update the structure.
For more information, see MQL Command Reference: businessobject Command: Expand Business
Object: Structure Clause in the online user assistance.
A business object does not need to have files associated with it. It is possible to have business
objects where the object’s attributes alone are all that is required or desired. However, there will be
many cases where you will want to associate external files with a business object. To make this
association, you must check the files into the object. This is called file checkin.
Checking in a file allows other users to access a file that might not otherwise be accessible. For
example, assume you have a file in your personal directory. You would like to make this file
accessible to your local group and the quality assurance group. In a typical computer environment,
there is no way to allow selective groups to have access while denying others. You could give the
file Group Access or World Access. The Group Access takes care of your immediate group but not
the quality assurance group. If you give World Access to the file, ANYONE can access it, not just
quality assurance. You can overcome this problem with 3DSpace.
The policy definition can designate when specified persons, groups, and roles have access to an
object. When an object is accessible, any files that are checked into that object are also accessible.
Therefore, if a group has read access to an object, they also have read access to any files checked
into the object. If the policy definition for an object includes enforced locking, no checkin for that
object is allowed until the lock is released, regardless if the file being checked in is going to replace
the checked-out file which initiated the lock or not.
When working with checked in files, keep in mind that the copy you check in will not change if you
edit your own personal copy. While you maintain the original, any edits that you make to that file
will not automatically appear in 3DSpace. The only way to have those changes visible to other
users is to either check in the new version or to make the edits while you are using the
3DEXPERIENCE Platform (i.e., with Open for Edit).
Checking in files is controlled by the Checkin Businessobject command. For more information, see
MQL Command Reference: businessobject Command in the online user assistance.
96 MQL Guide
For HTML/JSP-based applications, including the 3DEXPERIENCE apps and custom Framework
programs, large file checkins require both of the following:
• Checkins must be targeted for a FCS-enabled store/location (see Installing File Collaboration
Server for setup information.)
• Checkins must be invoked via the configurable file upload applet (see Common Components
User Guide for setup information.)
It is recommended that you enable both FCS and the file upload applet for all implementations,
even if you do not foresee working with files larger than 2 gb.
A lock on an object prohibits access to the files it contains, but still allows the object to be
manipulated in other ways.
But, if the checkout and edit are separate actions, the object should be manually locked. Without a
lock, two people might change an object’s file at the same time. With a lock, only the person who
locked the object manually is allowed to check files into the object. As with an automatic lock,
other users can view attributes, navigate the relationships, and even checkout an object’s file. But,
they cannot change the contents by checking in or deleting a file without unlocking the object.
It is possible for a locked object to be unlocked by a user with unlock access. For example, a
manager may need to unlock an object locked by an employee who is out sick. For more
information, see "Studio Modeling Platform Overview: Controlling Access: User Access" in the
online user assistance.
If another user has unlock privileges and decides to take advantage of them, the person who
established the lock will be notified via IconMail that the lock has been removed and by which
user. This should alert the lock originator to check with the unlocker (or the history file) before
checking the file back in to be sure that another version of the same file (with the same name and
format) has not been checked in, potentially losing all edits made by the unlocker.
If the object is governed by a policy which uses enforced locking, the object must be locked for
files to be checked in. Users must remember to lock an object upon checkout if they intend to
checkin changes, since the separate lock command will be disabled when locking is enforced.
The following commands control the movement of a business object into or out of a particular
state. A state defines a portion of an object’s lifecycle. Depending on which state an object is in, a
person, group, or role may or may not have access to the object. In some situations, a group should
have access but is prohibited because the object has not been promoted into the next state.
In addition to providing the approving signature, a comment was added to provide additional
information regarding the approval in the example above. In this case, the comment informs other
users that the object (Ken Brown’s car loan) has been approved up to an amount of $20,000. If the
customer asks for more, the approval would no longer apply and the bank manager might reject it.
The Approve Businessobject command provides a single approving signature. However, the
Approve Businessobject signature does not necessarily mean that the object will be promoted to the
next state. It only means that one of the requirements for promotion was addressed. Depending on
the state definition, more than one signature may be required.
98 MQL Guide
In this command, the reason for the bypass is clearly defined so that users understand the reason for
the initial bypass of the signature. As time passes, this information could easily become lost. For
that reason, you should include a Comment clause in the command even though it is optional.
The Ignore Businessobject command involves control over a single signature. An object is
promoted to the next state automatically when all requirements are met if the state was defined with
the Promote clause set to true. Bypassing the Ignore Businessobject signature does not necessarily
mean that the object will meet all of the requirements for promotion to the next state. It only means
that one of the requirements for promotion was circumvented. Depending on the state definition,
another user or condition may be required to approve the program.
Any other users can see the reason for the rejection. Since the signature was provided, the object
cannot be promoted unless someone else overrides the signature or the reason for rejection is
addressed.
The Reject Businessobject command provides a single signature. However, this signature does not
necessarily mean that the object will be demoted or completely prevented from promotion to the
next state. It only means that one of the requirements for promotion was denied. Depending on the
state definition, another user may override the rejection.
Unsign Signature
The Unsign Signature command is used to erase signatures in the current state of an object. Any
user with access to approve, reject, or ignore the signature has access to unsign the signature.
For example the command to unsign the signature "Complete" in object Engineering Order 000234
1 is:
unsign businessobject "Engineering Order" 000234 1 signature Complete;
Labeling an object as disabled within a state does not affect the current access. This means that the
designer can continue to work on the object in that state.
Now, assume that the object is currently in the Initial Release state and a promotion would place it
in the Testing state. How does the Override Businessobject command affect the object when it is
promoted? The object will be promoted directly from the Initial Release state into the Final Release
state.
When using the Demote Businessobject command, an object cannot be demoted if:
• The current state is disabled.
• The signature requirements for rejection were not met or overridden (ignored).
• There are no other states prior to the current state.
Once you have defined relationship types, connections or instances of a relationship type can be
made between specific business objects. Refer to Making Connections Between Business Objects
for the MQL commands: Connect Businessobject and Disconnect Businessobject. Other commands
that can be used to make connections and work with connections in general are described in the
following section.
Connections are also used to make associations between files, folders and modules in DesignSync
and business objects in Collaboration and Approvals, if you are using DesignSync stores for source
control. These types of connections are generally made in 3DEXPERIENCE apps, which use MQL
commands in implementation. For more information, see the Common Components User Guide:
About DesignSync File Access.
Connections can be accessed by MQL in two ways:
• by specifying the business objects on each end
Or:
• by specifying its connection ID.
The first method will work only if exactly one of a particular relationship type exists between the
two listed objects. Therefore, if connections are to be programmatically modified, the second
method, using connection IDs, is the safer approach.
Defining a Connection
There are two ways of creating a new instance of a relationship: the Connect Businessobject
command or the Add Connection command. Use the Add Connection command to make various
types of connections between either:
• 2 business objects
• a business object and a connection
• 2 connections
One business object or connection is labeled as the TO or TOREL end and one is labeled as the
FROM or FROMREL end. When the objects are equivalent, it does not matter which object is
assigned to which end. However, in hierarchical relationships, it does matter. Collaboration and
Approvals use the TO and FROM labels to determine the direction of the relationship.
The direction you select makes a difference when you examine or dissolve connections. When you
examine an object’s connections, you can specify whether or not you want to see objects that lead
to or away from the chosen object. When you disconnect objects, you must know which object
belongs where. Therefore, you should always refer to the relationship definition when working
with connections. To disconnect objects, see Making Connections Between Business Objects.
Creating connections that have a connection on at least 1 end eliminates the need to create dummy
business objects when modeling schema. For example, if a connection can not be used as an end
point, to connect object D to the R1 connection in the diagram below, you would have to create an
extra business object and an extra connection so that D is logically tied to R1.
You can connect an object or connection to or from a connection if you have to/from connect access
on the object or connection. Likewise, you can delete (disconnect) or modify the connection with
appropriate access on the object or connection that is on one end of it.
You cannot use Matrix Navigator to create connections that have a connection on one or both ends.
This must be done using MQL or Studio Customization Toolkit programs.
In this section:
• Queries
• Sets
• Tables
• Filters
• Cues
• Inquiries
105
Queries
A query is a search on the database for objects that meet the specified criteria. The query is
formulated by an individual and, in MQL, it must be saved for subsequent evaluation. A user has
access only to queries created during a session under her or his own context. It is then run or
evaluated and 3DSpace finds the objects that fit the query specification. The found objects are
displayed in Collaboration and Approvals or listed in MQL. If the found objects are often needed as
a group, they can be saved in a set which can be loaded at any time during an Collaboration and
Approvals or MQL session under the same context.
There are two steps to working with queries:
• Define either a saved query that you want to use again, or a temporary query to be used only
once for a quick search.
• Evaluate the query. The query is processed and any found objects can be put into a set.
Temporary queries allow you to perform a quick search for objects you need only once. In this case
you don’t have to first save the query itself as an object. For example, you might want to modify a
particular object that is named HC-4....., but you have forgotten its full name or capitalization. You
could perform a temporary search (without saving the actual query) using “HC-4*” to find all
objects that have a name beginning with the letters “HC-4”. From the resulting list, you could enter
the correct name in your modify command.
Saved queries allow you to find, for example, all drawings created for a particular project. You can
save the results of the query in a set. As the project proceeds, you can also name and save the query
itself to use again to update the set contents. Or you might want to repeatedly search for any objects
having a particular attribute or range of attributes. Saved queries provide a way of finding all the
objects that contain the desired information.
Defining a Query
To define a saved query from within MQL, use the Add Query command:
add query NAME [user USER_NAME] {ITEM};
A set is a logical grouping of business objects created by an individual user. Sets are often the result
of a query made by a user. For example, the user may want to view all drawings created for a
particular project or find information about objects having a particular attribute or range of
attributes. While sets can be manually constructed based on the needs and desires of the individual,
queries are a fast means of finding related business objects.
The contents of a set can be viewed at any time and objects can be added or deleted from a set
easily. However, a user has access only to sets created while in session under his/her context.
Understanding Differences
It is important to realize that sets are not the same as connections between business objects.
Connections also group business objects together in a window for users to analyze; however,
connections are globally known links rather than local links.
Defining a Set
Sets are often the result of a query. To save the contents of a query in a set, see MQL Command
Reference: query Command: Evaluate Query in the online user assistance.
To manually define a set from within MQL, use the Add Set command:
add set NAME [user USER_NAME][ADD_ITEM {ADD_ITEM}];
Filters limit the objects or relationships displayed in browsers to those that meet certain conditions
previously set by you or your Business Administrator. For example, you could create a filter that
would display only objects in a certain state (such as Active), and only the relationships connected
toward each object (not to and from). When this filter is turned on, only the objects you needed to
perform a specific task would display.
From Matrix Navigator browsers, filters that limit the number of objects that display can be very
useful. Each user can create her/his own filters from Matrix Navigator (or MQL). However, if your
organization wants all users to use a basic set of similar filters consistently, it may be easier to
create them in MQL, then copy the code to each user’s personal settings (by setting context).
Filters can be defined and managed from within MQL or from the Visuals Manager in Matrix
Navigator. Once the filters are defined, individual users can turn them on and off from the browsers
as they are needed.
In the Matrix Navigator browsers, filters display on the Filters tab page within the Visuals Manager
window, in the Filter bar and in the View menu.
It is important to note that filters are Personal Settings that are available and activated only when
context is set to the person who defined them.
Defining Filters
To define a new filter from within MQL, use the Add Filter command:
add filter NAME [user USER_NAME] [ADD_ITEM {ADD_ITEM}];
Cues control the appearance of business objects and relationships inside any browser. They make
certain objects and relationships stand out visually for the user who created them.
This appearance control is based on conditions that you specify such as attribute value, current
state, or lateness. Objects and relationships that meet the criteria may appear in any distinct color,
line, or font style.
You can save a cue and not make it active. This allows for multiple or different sets of conditions to
be used at different times or as a part of different Views. See “Using View Manager” in the Matrix
Navigator Guide. Cues are set using the Visuals Manager and saved as a query in your personal
settings. They can be activated from the Visuals Manager Cue tab or from the View menu.
From Matrix Navigator browsers, cues that highlight the appearance of certain objects can be very
useful. Each user can create her/his own cues from Matrix Navigator (or MQL). However, if your
organization wants all users to use a basic set of similar cues consistently, it may be easier to create
them in MQL, then copy the code to each user’s personal settings (by setting context).
Cues can be defined and managed from within MQL or from the Visuals Manager in Matrix
Navigator. Once the cues are defined, individual users can turn them on and off from the browsers
as they are needed.
In the Matrix Navigator browsers, they display on the Cues tab page within the Visuals Manager
window and in the View menu.
It is important to note that cues are all Personal Settings that are available and activated only when
context is set to the person who defined them.
Defining a Cue
From browsers, unique cues can be very useful when interacting with many objects. Each user can
create her/his own cues from Matrix Navigator (or MQL). However, if your organization wants all
users to see a basic set of similar cues consistently, it may be easier to create them in MQL, then
copy the code to each user’s personal settings (by setting context).
To create a new cue from within MQL, use the Add Cue command:
add cue NAME [user USER_NAME] [ADD_ITEM {ADD_ITEM}];
Inquiries can be evaluated to produce a list of objects to be loaded into a table in a JSP application.
In general, the idea is to produce a list of business object ids, since they are the fastest way of
identifying objects for loading into browsers. Inquiries include code, which is generally defined as
an MQL temp query or expand bus command, as well as information on how to parse the
returned results into a list of OIDs.
Defining an Inquiry
Business Administrators can create new inquiry objects if they have the Inquiry administrative
access. To create a new inquiry from within MQL, use the Add Inquiry command:
add inquiry NAME [ADD_ITEM {ADD_ITEM}];
This chapter discusses concepts on administrative objects used for extending applications.
• Programs
• History
• Administrative Properties
• Applications
• Dataobjects
• Webreports
111
Programs
Defining a Program
A program is created with the Add Program command:
add program NAME [ADD_ITEM {ADD_ITEM}];
Using Programs
For information on using programs in an implementation, see the Configuration Guide: About
Programs. It contains key information including:
• compiling programs
• extracting and inserting JPO code
• passing arguments
• Java options
The sections that follow include some basic MQL syntax for the above functionality.
Compile command
To force compilation before invoking a JPO method, use compile program. This is useful for
bulk compiling and testing for compile errors after an iterative change to the JPO source.
compile program PATTERN [force] [update];
Compiler flags can be adjusted using the MX_JAVAC_FLAGS environment variable. For more
information, see Live Collaboration Server: Configuring Live Collaboration: Live Collaboration
Settings: Optional Variables.
When a JPO is compiled or executed, any other JPOs which are called by that JPO or call that JPO
must be available in their most recent version. The compile command includes an update option
Execute command
You can run a program with the execute program command:
exec program PROGRAM_NAME [-method METHOD_NAME] [ARGS]
[-construct ARG];
where:
ARGS is zero or more space-delimited strings.
The -construct clause is used to pass arguments to the constructor. ARG is a single string. If
more than one argument needs to be passed to the constructor, the -construct clause can be
repeated as many times as necessary on a single command.
Extract command
Extracting the Java source in the form of a file out to a directory is useful for working in an IDE.
While in the IDE a user can edit, compile, and debug code. The extract program command
processes any special macros and generates a file containing the Java source of the JPO. If no
source directory is given, the system uses ENOVIA_INSTALL/java/custom (which is added to
MX_CLASSPATH automatically by the install program).
extract program PATTERN [source DIRECTORY]
In order to use the extract feature, the JPO name must follow the Java language naming convention
(i.e., no spaces, special characters, etc.). Only alphanumeric printable characters as well as '.' and
'_' are allowed in class names in the JPO.
Insert command
After testing and modifying Java source in an IDE, it is necessary to insert the code back into JPOs
in the database. The insert program command regenerates special macros in the Java source
as it is placed back into a JPO (reverse name-mangling). If the JPO does not exist, the insert
command creates it automatically.
insert program FILENAME | DIRECTORY;
For example:
insert program matrix/java/custom/testjpo_mxJPO.java
OR
insert program matrix/java/custom/
The later will insert all the .java files in the specified directory.
Collaboration and Approvals provides a history for each business object, detailing every activity
that has taken place since the object was created.
An object’s historical information includes:
• The type of activity performed on the object, such as create, modify, connect, and so on.
• The user who initiated the activity.
• The date and time of the activity.
• The object’s state when the activity took place.
• Any attributes applicable when the activity took place.
You can add a customized history through MQL to track certain events, either manually or
programmatically.
History records can be selected when printing or expanding business object, set, or connection
information using the MQL select clause. In addition, when printing all information about a
business object, set, or connection, history records can be excluded.
System administrators only can purge the history records of a business object or connection via
MQL. In addition, all history records of a business object or connection can be deleted with one
command.
History can be turned off in a single session by a System Administrator for the duration of the
session or until turned back on. In addition, if an implementation does not require history recording,
or requires only custom history entries, Collaboration and Approvals “standard” history can be
disabled for the entire system. Turning history recording off can improve performance in very large
databases, though certain standards may require that it is turned on.
History entries larger than 255 characters are truncated to 255 characters. This includes custom
history entries as well as Collaboration and Approvals history entries. This means that history logs
for the modification of long description or string attribute fields may be truncated.
When objects are created and then immediately modified within a trigger, the timestamp is often
identical. When this happens, the modify event may be logged before the create event, although
both will have the same timestamp.
For more information, see MQL Command Reference: history Command in the online user
assistance.
Defining a Property
Properties can be created and attached to an object at the same time using the add property
command. A property must have a name and be “on” an object. It can, optionally, define a link to
another administrative object using the “to” clause. This command, therefore, takes two forms,
with and without the “to” clause.
add property NAME on ADMIN_TYPE ADMIN_NAME [system] [to
ADMIN_TYPE ADMIN_NAME [system]] [value VALUE];
You can design your application’s data model such that you can mark part or all of it as private or
protected. The data you mark private cannot be accessed from any other project while the data you
mark protected can only be viewed and not modified. If your company is working on a top secret
government project, you will need to mark the data connected to this project as private to avoid any
accidental viewing or modification of data. You can do this by assigning an owning application to
your project.
An application is a collection of administrative objects (attributes, relationships and types) defined
by the Business Administrator and assigned to a project. It acts as a central place where all
application dependent associations to these other administration objects are defined. The
application members (the types, relationships etc) can have different levels of protection (private,
protected or public). This protection also extends to the objects governed by them. For example, if
you mark a relationship as protected, all connections of that type will also get marked as protected.
The advantage of assigning an owning application to a project is that it ensures data integrity. All
modifications to the data are handled by the owning application code which performs all necessary
checks to ensure complete data integrity. This prevents any unintended mishandling and possible
corruption of data. Thus, when an Collaboration and Approvals product (or any custom
application) tries to access data marked private or protected by connecting to the Server, it has to
specify the name of the owning application containing that data. You can specify an application
name only in the Studio Customization Toolkit.
In MQL and Business Modeler, a person can be assigned an owning application.
Defining an Application
An application is created with the Add Application command:
add application NAME [ADD_ITEM {ADD_ITEM}];
Dataobjects are a type of workspace object that provide a storage space for preference settings and
other stored values for users. Apps will use them for cached values for form fields, as well as to add
personalized pages to channels in PowerViews. Refer to Channels in Chapter 6 for more
information.
Settings stored in dataobjects are not limited in length.
Defining a Dataobject
Dataobjects can be created in MQL only.
To create a new dataobject, use the Add dataobject command:
add dataobject NAME [user USER_NAME] [ADD_ITEM {ADD_ITEM}];
A webreport is a workspace object that can be created and modified in MQL or using the
WebReport class in the Studio Customization Toolkit. Webreports are used to obtain a set of
statistics about a collection of business objects or connections. The administrative definition of a
webreport includes:
• search criteria which specifies the full set of objects to be examined.
• one or more groupby criteria which specify how to organize the objects into groups
• one or more data expressions to be calculated on each group. These are expressions suitable for
evaluating against a collection of business objects – such as count, average, maximum,
minimum, etc.
Once a webreport is created it can be evaluated to produce a webreport result, which consists of
both the organized set of data values and objects for the subgroups. It can be saved to the database
(with or without the corresponding business objects) if desired. Webreport results can also be
archived and a webreport can store any number of archived results as well as a single result referred
to as “the result”. Webreports are used mainly by the Business Metrics component of Business
Process Services, but can be used in custom applications as well.
Defining a Webreport
To define a webreport from within MQL use the add webreport command:
add webreport NAME [user USER_NAME][ADD_ITEM {ADD_ITEM}];
Evaluating Webreports
When a webreport is evaluated, it can either report the results back to the caller, save them in the
database, or both. When results are saved, so is the following information:
• the date/time evaluated;
• the time it took to evaluate;
• the name of the person who ran it (the context user).
Also when results are saved, they overwrite any previously saved results unless those results have
been archived. Any number of results can be archived.
This chapter discusses concepts on administrative objects used for modeling web elements.
• Commands
• Menus
• Channels
• Portals
• Tables
• Forms
123
Commands
Business Administrators can create new command objects if they have the Menu administrative
access. Commands can be used in any kind of menu in a JSP application. Commands may or may
not contain code, but they always indicate how to generate another Web page. Commands are child
objects of menus — commands are created first and then added to menu definitions, similar to the
association between types and attributes. Changes made in any definition are instantly available to
the applications that use it.
Commands can be role-based, that is, only shown to particular users. For example, a number of
commands may only be available when a person is logged in as a user defined as Administrator.
When no users are specified in the command definitions, they are globally available to all users.
Defining a Command
To define a command from within MQL use the Add Command command:
add command NAME [ADD_ITEM {ADD_ITEM}];
You cannot have both a command and a menu with the same name.
ADD_ITEM is an Add Command clause that provides additional information about the command.
For more information, see MQL Command Reference: command Command in the online user
assistance.
When using a macro, surround it with quotes to ensure proper substitution if a value contains
spaces.
Directory Macros
The following table provides the list of directory specific macros used in the configuration setting.
Directory Macros
${COMMON_DIR} To substitute the “common” directory below “ematrix” directory. The substitution is done
with reference to any application specific directory and it is relative to the current directory.
${ROOT_DIR} To substitute the “ematrix” directory. The substitution is done with reference to any
application specific directory below “ematrix” and it is relative to the current directory.
${SUITE_DIR} The macro to substitute the application specific directory below “ematrix” directory. The
substitution is done based on the “Suite” to which the command belongs. and it is relative to
the current directory.
Business Administrators can create new menu objects if they have the Menu administrative access.
Menus can be used in custom Java applications. Before creating a menu, you must define the
commands that it will contain, since commands are child objects of menus — commands are
created first and then added to menu definitions, similar to the association between types and
attributes. Changes made in any definition are instantly available to the applications that use it.
Menus can be designed to be toolbars, action bars, or drop-down lists of commands.
Creating a Menu
To define a menu from within MQL use the Add Menu command:
add menu NAME [ADD_ITEM {ADD_ITEM}];
You cannot have both a command and a menu with the same name.
ADD_ITEM is an Add Menu clause that provides additional information about the menu.
For more information, see MQL Command Reference: menu Command in the online user
assistance.
Channels are essentially a collection of commands. They differ from menus in that they are not
designed for use directly in an application, but are used to define the contents of a portal. Channels
and portals are installed with the Framework and used in apps to display PowerView pages, but
may also be created for use in custom Java applications.
The use of the term “Portal” here refers to the administration object, and not to the broader
internet definition described in JSR 168.
Business Administrators can create channel objects if they have the portal administrative access.
Since commands are child objects of channels, commands are created first and then added to
channel definitions, similar to the association between types and attributes. Likewise, channels are
created before portals and then added to portal objects. Changes made in any definition are
instantly available to the applications that use it.
Channels created in MQL can optionally be defined as a user’s workspace item.
Creating a Channel
To define a channel from within MQL use the add channel command:
add channel NAME [user USER_NAME] [ADD_ITEM {ADD_ITEM}];
You cannot have both a channel and a portal with the same name.
USER_NAME can be included if you are a business administrator with person/group/role access
defining a channel for another user. This user is the item’s “owner.” If the user clause is not
included, the channel is a system item.
ADD_ITEM is an add channel clause that provides additional information about the channel.
For more information, see MQL Command Reference: channel Command in the online user
assistance.
A portal is a collection of channels, as well as the information needed to place them on a Web page.
Some portals are installed with the Framework and used in apps to display PowerView pages, but
they may also be created for use in custom Java applications. Business Administrators can create
portal objects if they have the portal administrative access.
The use of the term “Portal” in this chapter refers to the administration object, and not to the
broader internet definition described in JSR 168. In headings in the documentation we use the
terms 3DSpace portal and Public portal when a discernment needs to be made.
Before creating a portal, the channels that it will contain must be defined. Channels are child
objects of portals — channels are created first and then added to portal definitions, similar to the
association between types and attributes. Changes made in any definition are instantly available to
the applications that use it.
Portals created in MQL can optionally be defined as a user’s workspace item.
Creating a Portal
To define a portal from within MQL use the add portal command:
add portal NAME [user USER_NAME] [ADD_ITEM {ADD_ITEM}];
Tables can be defined to display multiple business objects and related information. Each row of the
table represents one business object. Expressions are used to define the columns of data that are
presented about the business objects in each row. When you define a table, you determine the
number and contents of your table columns.
There are two kinds of tables:
• A User table is a user-defined template of columns that can be used when objects are displayed
in the Matrix Navigator (Details browser mode only), or in MQL with the Print Table
command.
User tables are created in MQL, or in Matrix Navigator’s Visuals Manager and displayed when
Matrix Navigator is in details mode. In Matrix Navigator, tables that users create are available
from the Views/Tables menu. This enables viewing different information about the same object
with a single mouse-click.
Tables can be added as part of the definition for a customized View. Each time that View is
activated, the Table defined for it displays.
Users can save Table definitions by name (as personal settings) to turn on or off as needed. A
single table may become part of several Views, being activated in one, and available in
another. Refer to the Matrix Navigator Guide: Using View Manager for more information on
Views.
From Matrix Navigator browsers, tables that present information in a familiar format can be
very useful. Each user can create her/his own tables from Matrix Navigator (or MQL).
However, if your organization wants all users to use a basic set of similar tables consistently, it
may be easier to create them in MQL, then copy the code to each user’s personal settings (by
setting context).
• A System table is an Administrator-defined template of columns that can be used in custom
applications. These tables are available for system-wide use, and not associated with the
session context. Each column has several parameters where you can define the contents of the
column, link data (href and alt), user access, and other settings. For example, a user could click
on a link called Parts to display a system table containing a list of parts. The other columns in
the table could contain descriptions, lifecycle states, and owners.
System tables are created by business administrators that have Table administrative access, and
are displayed when called within a custom application.
System table columns can be role-based, that is, only shown to particular users. For example,
the Parts table might have a Disposition Codes column that is shown only when a person is
logged in as a user defined as a Design Engineer. Or a user defined as a Buyer might be shown
a column in a table that is not seen by a Supplier user. When no users are specified in the
command and table definitions, they are globally available to all users.
When business objects are loaded into a table, Collaboration and Approvals evaluate the table
expressions for each object, and fills in the table cells accordingly. Expressions may also apply to
relationships, but these columns are only filled in when the table is used in a Navigator window.
You can sort business objects by their column contents by clicking on the column header.
Creating a Table
To define a table from within MQL use the Add Table command:
add table NAME user USER_NAME [ADD_ITEM {ADD_ITEM}];
ADD_ITEM is an Add Table clause which provides additional information about the table.
For more information, see MQL Command Reference: table Command in the online user
assistance.
You must be a Business Administrator to define a form, and have form administrative access.
Defining a Form
Use the Add Form command to define a form:
add form NAME [web] [ADD_ITEM {ADD_ITEM}];
NAME is the name you assign to the form you are creating.
web is used when creating a “Web form.” This distinguishes forms to be used in HTML/JSP
applications from those used in the Studio Modeling Platform.
ADD_ITEM is an Add Form clause which provides additional information about the form.
For more information, see MQL Command Reference: form Command in the online user assistance.
133
Maintaining the System
The duties of the System Administrator are to maintain and troubleshoot the system. The System
Administrator should also be the on-site point of contact for all software updates, revisions, and
customer support requests. Specific duties include:
• Controlling System-wide Settings
• Validating the 3DSpace Database
• Maintaining and monitoring clients (See the Administration Guide: Maintaining and
Monitoring Clients.)
• Monitoring server diagnostics (See the Administration Guide: Diagnostic Commands.)
• Developing a Backup Strategy
Other responsibilities are covered in these chapters:
• Studio Modeling Platform Overview: Building the System Basics in the online user assistance
• Working with Import and Export in Chapter 8
Case-Sensitive Mode
Collaboration and Approvals by default is case-sensitive. However, when using Oracle Enterprise
Edition, Oracle Standard Edition, or SQL Server, Collaboration and Approvals can be configured to
operate in case-insensitive mode.
Oracle Standard Edition is not available for 64-bit operating systems. Oracle Enterprise Edition is
recommended for maximum scalability and performance.
It is very important that MQL be closed and restarted after setting the system casesensitive
setting to On.
3DSpace setup
3DSpace/Oracle databases must be at schema Version 10.5 or higher to be able to turn case
sensitivity off. For databases older than 10.5, you must run the MQL upgrade command with
Version 10.5 or higher. You also must convert unique constraints to unique indices in Oracle.
There is the real possibility that duplicate records will exist if you have used the database before
turning off the casesensitive setting. For example, in a case sensitive environment, you could
have users named “bill” and “Bill”, which would cause unique constraint violations if an attempt
was made to make this database case insensitive (add unique indices). The MQL command
validate unique is provided to identify these conflicts so that they can be resolved prior to
turning off the setting. Once resolved, you then turn off the casesensitive system setting,
which defaults to on, and reindex the vaults to switch to unique indices.
You can run the validate unique command against pre-10.5 databases using MQL 10.5 or
higher to identify conflicts before upgrading.
5. Calculate or update statistics on all tables by executing the following MQL command:
<mql> validate level 4;
The validate level 4 command should be run after any substantial data load operation, and
periodically thereafter, in order to update the statistics. Refer to Validating the 3DSpace
Database for details.
3DSpace is now ready to use in case-insensitive mode.
The foreign database may need its own configuration to run in a case insensitive manner.
If the adaplet has case-sensitivity turned on and is in extend or migrate mode, then types must use
mapped ids. Refer to the Adaplet Programming Guide for more information.
Once this command has been run, when users change an object’s vault via any application (that is,
Studio Modeling Platform or Web applications, or custom Studio Customization Toolkit
applications), all IconMails that reference the object are fixed, as well as user’s sets.
Database Constraints
Some versions of Oracle have a bug that limits performance and concurrency when an operation
uses a column that has a foreign key constraint and that column is also not indexed. Such columns
can cause deadlocks and performance problems. For systems that use foreign keys extensively, this
leads to a trade off that must be made between performance, storage, and use of foreign keys. You
can use the set system constraint command to tailor the schema for one of three possible modes of
operation::
set system constraint |none |;
|index [indexspace SPACE] |
|normal |
• Normal
The normal system setting results in a schema that has foreign keys that are not indexed; that
is, foreign key constraints are configured as they have been in pre-version 10 releases. This is
the default setting. Databases using this setting are subject to the Oracle concurrency bug
regarding non-indexed foreign keys.
• Index
The index setting results in an Oracle index being added to every column that is defined as a
foreign key, and has no existing index. Overhead in both storage and performance is added
since updates to foreign keys also require updates to their corresponding index. This option
should be used in development and test environments, where there is substantial benefit in the
enforcement of foreign key constraints, and the negative storage/performance impact will not
affect large numbers of users.
When issuing the command to add indices to the system, you can specify the tablespace to use
for the indexing operation.
When set, the system gets the time in GMT from the db server. GMT can also be determined based
on the local time and time zone of the server object defined by the System administrator.
When setting the system decimal character, be sure to use the setting that is implied by the
database’s NLS_LANG setting. The default setting is period '.'. So, if the database setting for
NLS_LANG is AMERICAN_AMERICA.WE8ISO8859P15, Oracle expects a period for the
decimal symbol (as indicated by the territory setting of AMERICA), and 3DSpace makes the
necessary conversion, once the following command is run:
set system decimal .;
The command set system decimal CHARACTER; is not supported for use with databases
other than Oracle. For non-Oracle databases, the data is always stored with '.' but displayed based
on the desktop client’s MX_DECIMAL_SYMBOL setting, or in Web based implementations the
locale of the browser.
For more information on configuring 3DSpace for multiple language support, see the following
topics in the Administration Guide:
• Localizing 3DSpace
• Language Support
• Configuring a Japanese Web Environment
By default, the setting is off, which means that empty names are not allowed. MQL and any other
program code will issue an error if any attempt to make a business object have an empty name is
made. It will also cause a warning to be issued if a query specifies an empty string (“ ”) for the
name. (The query will not error out and will not abort any transaction going on.) If the setting is on,
the system allows empty names for objects in MQL only.
By default, history is on. When turned off, custom history records can be used on the operations
where history is required, since it will be logged regardless of the global history setting.
After this command has been run, business administrators need a password when changing context
to another person. Only system administrators can change context to any other person without a
password.
A System Administrator can re-enable business administrators to change context without a
password using:
set system privilegedbusinessadmin on;
System Tidy
In replicated environments, when a user deletes a file checked into an object (via checkin overwrite
or file delete), by default all other locations within that store maintain their copies of the now
obsolete file. The file is deleted only when the administrator runs the tidy store command.
You can change the system behavior going forward so that all future file deletions occur at all
locations by using:
set system tidy on;
Since this command changes future behavior and does not cleanup existing stores, you should then
sync all stores, so all files are updated. Once done, the system will remain updated and tidy, until
and unless system tidy is turned off.
Running with system tidy turned on may impact the performance of the delete file operation,
depending on the number of locations and network performance at the time of the file deletion.
The MQL validate command enables you to check the correctness and integrity of the 3DSpace
database. See the Server Installation Guide: Upgrading the Database after Installing a New
Version of Software for complete syntax and clauses for working with the MQL validate command.
Correct command
The MQL correct command can be used by System Administrators as directed by Dassault
Systèmes Technical Support, to correct anomalies caused by older versions of the product. You
must be certain that no users are logged in or can log in while correct is running.
Confirm that no users are connected, using the sessions command or Oracle tools, and temporarily
change the bootstrap so that no one can login while correct is running.
There are several forms of the command. Each form is described in the sections that follow.
Correct Vault
The correct vault command can be used to validate or correct the following relationship issues in a
database:
1. “Stale” relationships - Relationships that reference a business object that does not exist.
Since there is no way to determine which business object should be referenced, the relationship
is deleted when the correct command is issued with “fix”.
A sample of the output generated when fixing this issue is shown below:
// Missing to/from businessobjects
From vault Zephyr to vault Zephyr
From vault Zephyr to vault KC
remove stale relationship
type: BrokenRel
from: 8286.42939.11584.38392
to: BrokenRel child1 0
remove stale relationship
type: BrokenRel
from: 8286.42939.11584.38392
to: BrokenRel child1 0
From vault KC to vault Zephyr
From vault KC to vault KC
Correct finished in 0.12 second(s)
Total of 2 problem(s) encountered and fixed
If in validate mode, the last line would say:
Total of 2 problem(s) encountered and validated
2. extra “to” end - A cross vault relationship has a valid “to” side object, but there is no
corresponding “from” object.
The relationship is deleted when the correct command is issued with “fix” as there is
insufficient information to reconstruct the relationship - its attributes and history are missing.
Syntax
The syntax of the correct vault command is:
correct vault VAULTNAME [to VAULTNAME] [type REL1{,REL2}] [verbose]
[fix] [validate];
Unless “fix” is specified, the command will run in “validate” mode.
If you include both “fix” and “validate,” an error will occur asking you to specify just one of the
options. If you use “correct validate” without any arguments, all relationships’ from objects are
checked and a report is generated on stdout that lists all problems found.
Each argument is described below.
type REL1{,REL2}
Inspects only relationship types listed. If not specified, all the relationship types in the system will
inspected for problems.
verbose
Causes the program to output the SQL needed for repair to stdout. Set to false by default.
fix
Fixes the database. Set to false by default.
validate
Validates the database. Reports broken relationships but no corrections are made. Set to true by
default.
Transactions
The correct vault command operates in two passes. The first pass is a quick scan through the
database without performing any row level locks. The second pass gathers detailed information on
relationships reported as “suspect” during the first pass.
During concurrent use of the system, it is entirely possible that the validate function on a vault may
report errors that do not actually exist in the database since it is operating without the benefit of
locks (the data many be changing while it is being examined). However, during the second pass,
any suspicious data is fully re-qualified using row level locks, making the function safe to use
while the system is live.
Note that with any general purpose application that uses locks, a deadlock situation may occur if
other applications are locking the same records in an inconsistent fashion. Deadlocks are highly
unlikely while using correct vault since the data that is being locked (e.g. a 'stale' relationship) is
generally unusable by other applications. However, if deadlock should occur, simply reissue the
correct vault command and allow it to run to completion.
This two pass transaction model is only used by the correct vault command. While "correct vault" is
designed to run while in concurrent use, it is recommended that for all system administrator
operations like this one, it be issued when there are no other users logged on.
Whenever any form of the correct command is executed in fix mode, you receive the following
warning and prompt for confirmation:
Correct commands may perform very low level modifications to your
database.
Use the 'sessions' command to check that no users are logged in.
It is strongly recommended that you change bootstrap password to insure
that no users log in during correct process, and turn verbose on to
record corrective actions.
Correct Attribute
To verify the integrity of attributes and types, each type in the database can first be checked to
ensure that no attribute data or attribute range values are missing. The following command will
return a list of objects of the specified TYPE that have missing data:
MQL<> correct attribute validate type TYPE;
where TYPE is a defined type in 3DSpace. If corrections must be made, MQL will provide the
business object type, name, and revision, as well as what attribute data is missing, as follows:
Business object TYPE NAME REVISION is missing attribute ATTRIBUTE_NAME
Be sure to run this command for each type in the database.
If any business objects are returned by the correct attribute validate command, those
business objects must be fixed with the following command:
MQL< > correct attribute modify type TYPE_NAME attribute
ATTRIBUTE_NAME vault VAULT_NAME;
Where TYPE_NAME is the name of a business type to be corrected. When this command is
completed all business objects that have missing attributes will have those attributes back. The
value of the attribute will be the default value.
Where ATTRIBUTE_NAME is the name of the attribute that is missing from some objects.
Where VAULT_NAME is name of the vault in which business objects of type TYPE_NAME will
be examined and corrected if needed.
Run this command for each vault in the database. Only those business objects that were missing the
attribute will be modified. The added attribute on these objects will be initialized to its default
value, and MQL will output confirmation messages similar to:
count of BOs of type 'TYPE' in vault 'VAULT_NAME' = 1
processing attribute = 'ATTRIBUTE_NAME'
business obj '51585.1271.52275.16291' having db id '-869056605' with type
'TYPE_NAME' is missing attr 'ATTRIBUTE_NAME'
Total objects processed = 1
Correct Relationship
Correct relationship is used to correct relationship attribute data:
mql<> correct relationship;
Attributes on relationships that connect objects in different vaults are stored in the from-side vault.
This command removes attributes if they exist in the to-side vault.
Correct Set
Sets can be validated either across the entire database, or on a server by server basis using the
following:
MQL<> correct set validate [server SERVER_NAME];
Correct State
To verify the integrity of all states in the database or on a single vault use:
MQL<> correct state validate [vault VAULT_NAME];
Without the vault clause all states in the database are checked. If you include the vault clause, only
that vault is validated. You can then fix the states using:
MQL<> correct state [vault VAULT_NAME];
Because there are a number of factors that can cause a database failure, including power loss,
hardware failure, natural disasters, and human error, it is important that you develop both a backup
and a recovery plan to protect your database. It is not enough that you develop a recovery plan,
however. You must also test that recovery plan to ensure that it is adequate before your data is
compromised. Finding out that your recovery plan is inadequate after you have already lost your
data will not do you much good. Also, testing of the recovery plan may indicate changes you need
to make to your backup strategy.
Inventories of all stores should be performed nightly as part of the backup procedure. For more
information, see MQL Command Reference: store Command: Inventory Store Command in the
online user assistance.
3DSpace stores each attribute and “basic” property of an object in a separate row in the database,
allowing flexible and dynamic business modeling capabilities. (Basic properties include type,
name, revision, description, owner, locker, policy, creation date, modification date, and current
state). This has the side effect of requiring extra SQL calls (joins) when performing complex
queries and expands that specify multiple attribute or basic values. To improve performance of
these operations, you can define an index. In fact, test cases show marked improvement on many
types of queries and expands when an index is in place.
Queries and expands will choose the “best” index to perform the operation. If 2 indices are equally
qualified to perform the operation, the first one found will be used.
An index is a collection of attributes and/or basics, that when enabled, causes a new table to be
created for each vault in which the items in the index are represented by the columns. If a
commonly executed query uses multiple attributes and/or basics as search criteria, you should
consider defining an index. Once enabled, searches involving the indexed items generate SQL that
references the index table instead of the old tables, eliminating the need for a join.
A query that doesn’t use the first specified item in an index will not use that index. Therefore, when
creating an index, specify the most commonly used item first.
When an index is created or items are added or removed from it, the index is by default disabled.
The new database tables are created and populated when the index is enabled. This step can be
time-consuming; however, it is assumed that an index will be enabled by a system administrator
once when created or modified, and will remain enabled for normal system operation.
For expands, 3DSpace looks for and uses an index that is associated with relationships; that is, an
index that has a relationship attribute as the first item in it.
Creating an index is only one way of optimizing performance. A properly tuned database is critical.
While the Installation and MQL Guides provide some guidelines and procedures, refer to your
database documentation for tuning details.
Write operations of indexed items occur in 2 tables instead of just 1 and so a performance penalty
is paid. This has a negligible effect in cases where end users may be modifying a few values at a
time, but you should disable indices prior to performing bulk load/update operations. Re-enabling
the indices after the bulk update is more efficient than performing the double-bookkeeping on a
value-by-value basis during the bulk update.
PROS CONS
Excellent for reads. Write performance is impacted (data is
duplicated).
Query execution runtimes are More disc space is required (for duplicate
significantly reduced data).
Table joins are significantly reduced. Greater potential for deadlock during write
operations. (more data in one row as opposed
to separate rows within separate tables).
Item order in the definition of the index is
important, since if the operation doesn’t use
the first item, the index is skipped.
Also, keep in mind that attributes that have associated rules cannot be included in an index.
Defining an Index
An index is created with the add index command:
add index NAME [unique] [ADD_ITEM {ADD_ITEM}];
Enabling an Index
An index must be enabled before it is used to improve performance. The process of enabling an
index generally takes 0.01 second per object in the database. Some rough processing times that can
be expected are shown in the table below:
To optimize the performance, validating the tables is recommended. You should disable an index
before performing bulk loads or bulk updates.
Creating and enabling indices are not appropriate actions to be performed within explicit
transaction boundaries, particularly if additional operations are also attempted before a commit.
Index Tracing
Tracing can be enabled to detect queries/expands that can benefit by using a new or modified index.
When enabled, messages are displayed whenever a query or expand is executed that fails to find an
associated index. A message is output for each item in the query or expand that could be in an index
(an attribute or basic property). The intent of this tracing is to highlight queries and expands that
use indexable items, none of which are the first item in any index (so no index is used to optimize
the operation).
To enable the index trace messages, use the MQL command:
trace type INDEX on;
or set the environment variable:
MX_INDEX_TRACE=true
When this trace type is enabled, trace messages will be displayed in the format:
No index found for attribute[NAME1],attribute[NAME2],BASIC3…
The items in the trace message may or may not be in a defined index. However, even if they are part
of an enabled index, they are not the first item in it, and so the index is not usable for that query or
expand.
This chapter discusses concepts about exporting and importing administrative and business
objects.
In this section:
• Overview of Export and Import
• Exporting
• Importing
• Migrating Databases
153
Overview of Export and Import
Administrative definitions, business object metadata and workflows, as well as checked-in files,
can be exported from one root database and imported into another. Exporting and importing can be
used across schema of the same version level, allowing definitions and structures to be created and
“fine tuned” on a test system before integrating them into a production database.
When you export a business object, you can save the data to a exchange file or to an XML format
file that follows the Matrix.dtd specification. An exchange file is created according to the exchange
Format. This format or the XML format must be adhered to strictly in order to be able to import the
file.
Before exporting any objects, it is important to verify that MQL is in native language mode.
Exporting in the context of a non-native language is not supported.
Export Command
Use the Export command to export the definitions of a database. The complete export command for
administrative objects is as follows:
export ADMIN_TYPE TYPE_PATTERN [OPTION_ITEM [OPTION_ITEM]...]| into | file FILE_NAME
| onto |
[exclude EXCLUDE_FILE] [log LOG_FILE] [exception EX_FILE];
For more information, see MQL Command Reference: export Command in the online user
assistance.
XML Clause
Use the XML clause as an OPTION_ITEM in any Export command to export administrative or
business objects in XML format. To ensure that the XML file(s) reside in the same directory as the
XML DTD, you can export files to the XML folder (in your ENOVIA_INSTALL directory) where
the DTD is installed. Alternatively, you can specify another location in your Export command and
copy the DTD into that directory. Use the into clause in your Export command and specify a full
directory path, including file name. For example:
XML Command
Use the XML command to turn XML mode on or off as a global session setting. The complete
XML command syntax is:
xml [on|off];
Omitting the on/off switch causes XML mode to be toggled on or off, depending on its current
state. XML mode is off by default when you start an MQL session.
For example, to export a person named “guy” using an XML command along with an Export
command, you can enter:
xml on;
export person guy into file
c:\enoviaV6R2011\studio\xml\person.xml;
If you need to export several objects to XML format, using the XML command to turn on XML
mode first can eliminate the need to re-enter the XML clause in each Export command as well as
the possibility of an error if you forget.
XML Output
The XML export format typically generates a file 2 to 3 times larger than the standard export
format. To conserve space, subelements are indented only if verbose mode is turned on. Indentation
makes output more readable but is not required by an XML parser. Some XML viewers (like
Internet Explorer 5.0) will generate the indentation as the file is parsed.
The next example shows XML output when you use the Export command, with XML mode turned
on, to export a person named “guy” during a continuation of the same MQL session. While more
intelligible to a user, this code creates a larger output file than the standard export format.
MQL<3>xml on;
MQL<4>verbose on;
MQL<5>export person guy;
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!-- (c)MatrixOne, Inc., 2000 -->
<!DOCTYPE ematrix SYSTEM "ematrixml.dtd">
<ematrix>
<creationProperties>
<release>8.0.2.0</release>
<datetime>2000-05-05T17:57:19Z</datetime>
<event>export</event>
<dtdInfo>&ematrixProductDtd;</dtdInfo>
</creationProperties>
<person id="0.1.31721.46453">
<adminProperties>
<name>guy</name>
</adminProperties>
<fullName>Guy</fullName>
<fullUser/>
<businessAdministrator/>
<systemAdministrator/>
When migrating objects or entire databases, it is important to import in the correct order:
1. Import all administrative objects first.
2. Import all business objects.
3. Import workspaces from the same exported ASCII data file as was used to import Persons.
Refer to Importing Workspaces for more information.
4. Import properties of the administrative objects that have them. The same file that was used to
import the administrative objects should be used. Refer to Importing Properties for more
information.
For more migration strategies refer to Migrating Databases.
Import Command
Use the Import command to import administrative objects from an export file to a database. The
export file must be in Exchange Format or in an XML format that follows the Matrix.dtd
specification.
import [list] [property] ADMIN_TYPE TYPE_PATTERN [OPTION_ITEM [OPTION_ITEM]...]
from file FILENAME [use [FILE_TYPE FILE [FILE_TYPE FILE]...];
For more information, see MQL Command Reference: import Command in the online user
assistance.
Importing Servers
If a server object is imported (via MQL or Oracle) into a different Oracle instance or user than it
was exported from, the username and password settings of the server must be modified before
distributed access is available. This is particularly important if an upgrade will follow the import,
since all servers must be accessible to the machine doing the upgrade.
Importing Workspaces
Workspaces contain a user’s queries, sets, and IconMail, as well as all Visuals. Workspaces are
always exported with the person they are associated with. However, when Persons are imported,
the workspace objects are not included. This is because they may rely on the existence of other
objects, such as Types and business objects, which may not yet exist in the new database.
Workspaces must be imported from the same .mix file that was used to import persons. For
example:
import workspace * from file admin.mix;
Or:
import workspace julie from file person.mix;
Finally, workspaces and any “missed” properties are imported. Note that properties may exist on
workspace objects, so it is best to import properties after workspaces:
import workspace * from file person.exp;
import property attrib * from file attrib.exp;
import property program * from file program.exp;
import property type * from file type.exp;
import property person * from file person.exp;
If the export file contains a lot of other admin data and you want to “import admin *”, you can use
import options to avoid errors when the attributes are processed. For example, if you know you
want the objects in the export file to supersede any objects of the same type/name in the database
use the following:
import admin * overwrite from file /temp/export.exp;
When migrating entire databases or a large number of objects, it is important to import in the
following order:
1. Import all administrative objects first. For example:
import admin * from file admin.mix;
3. Import workspaces from the same exported ASCII data file as was used to import Persons. For
example:
import workspace * from file admin.mix;
Or:
import workspace julie from file person.mix;
Workspaces contain a user’s queries, sets, TaskMail, and IconMail, as well as all Visuals.
Workspaces are always exported with the person with which they are associated. However,
when Persons are imported, the workspace objects are not included. This is because they may
rely on the existence of other objects, such as Types and business objects, which may not yet
exist in the new database.
4. Import properties of administrative objects.
When administrative objects are imported, 3DSpace imports all the objects without their
properties and then goes back and imports both system and user properties for those objects. If
administrative objects were exported in pieces, such as all Types in one file, all Persons in
another, then properties should be explicitly imported with the import property
command. Refer to Importing Properties for more information.
Migrating Files
When migrating business objects, there are three options for its files:
1. By default, both file metadata and actual file contents are written to the export file for business
objects exported with their revision chain.
3DSpace UUencodes the file and writes it to the export data file, along with business object
metadata. Pointers to the files are guaranteed because the file is recreated during import. In this
case, any file sharing is lost, (as when revisions use the same file list—each revision in the
chain gets its own copy of the file).
2. Add the !file clause to not include any file metadata or content.
3. Use the !captured clause to not include captured store file content.
This option writes only the fully qualified path of checked in files in the data file, along with
business object metadata.
When migrating databases, most often the !captured option is recommended. This will facilitate
the process, in that the .mix files will not be as large, and therefore will not require as much disk
space or processing time to complete the migration. Once the import is complete, the objects will
point to the appropriate files in the same location.
Comparing Schema
This section describes how to compare two schemas to determine the differences between them. A
schema is all the administrative objects needed to support an app. Use schema comparison to
compare:
• Different versions of the same schema to manage changes to the schema.
• Two schemas from different databases so you can merge the schemas (for example, merge a
checkout system with a production system).
The process of comparing schema involves two main steps:
1. Create a baseline sample of one schema using XML export. See Creating a Baseline.
2. Analyze the differences between the baseline sample and the other schema (or a later version
of the same schema) using the compare command. You specify the administrative types
(attributes, relationships, etc.) and a name pattern (for example, all attributes beginning with
“Supplier”) to compare. Each compare command outputs a single log file that contains a
report. The report lists the administrative objects in the baseline export file that have been
added, deleted, and modified. See Comparing a Schema with the Baseline.
If your goal is to merge the two schemas by making the necessary changes to one of the schemas
(sometimes called “applying a delta”), you can make the changes manually or by writing an MQL
script file that applies the changes to the target schema.
Creating a Baseline
The first step for comparing two schemas is to establish a baseline for analysis by sampling one of
the schemas. You create a baseline by exporting administrative objects to XML format. You can use
any option available for the export command to create the baseline export files. For information on
options and more details about the export command, see Export Command.
Use the following guidelines to perform the export.
• Start MQL using a bootstrap file that points to the database containing the schema for which
you want to create the baseline.
• There are two ways to produce an XML export file: toggle on XML mode and issue a normal
export command, or issue a normal export command but include the XML keyword. For
example:
xml;
export ADMIN_TYPE TYPE_PATTERN into file FILENAME;
Or the equivalent:
export ADMIN_TYPE TYPE_PATTERN xml into file FILENAME;
• It’s best to create separate a export file for each administrative type and to keep all the objects
of a type in one file. For example, export all attributes to file attributes.xml, all relationships to
relationship.xml, etc. This keeps the baseline files to a reasonable size, and also lets you
compare specific administration types, which makes it easy to produce separate reports for
each administration type. If you need to identify subsets of objects within an export file to
focus the analysis, you can do so using the compare command.
• The compare command requires that the ematrixml.dtd file be in the same directory as the
export files. Therefore, you should create the export files in the directory that contains the dtd
file or copy the dtd file into the directory that contains the export files. If you don’t specify a
path for the export file, 3DSpace creates the file in the directory that contains mql.exe file.
The following table shows examples of export commands that export different sets of
administrative objects. All the examples assume the XML mode is not toggled on and that the
ematrixml.dtd file is in the directory d:\Matrix\xml.
When issuing the command, make sure you start MQL using a bootstrap file that points to the
database that you want to compare with the schema for which you created the baseline.
The compare command analyzes only administrative objects and ignores any business object
instances in the baseline export file.
Where unordered lists are used, their order resulting from a query is not guaranteed. This may
potentially yield false differences during compare. Unexpected differences reported on unordered
list items should be verified by examining the log or command output.
The ADMIN_TYPE clause specifies which administrative types to compare. Valid values are:
The value admin compares all administrative types of the name or pattern that follows. For
example, the clause “admin New*” compares all administrative objects with the prefix “New.” All
other ADMIN_TYPE values compare specific administrative types. For example, to compare all
policies, you could use:
compare policy * from file
d:\enoviaV6R2011\studio\xml\policy.xml;
To compare objects of a particular type whose names match a character pattern, include the pattern
after the ADMIN_TYPE clause. For example, to compare only relationships that have the prefix
“Customer”, you could use:
compare relationship Customer* from file d:\enoviaV6R2011\studio\xml\relationship.xml;
workspace Option
The workspace option applies only when comparing administrative types that can have associated
workspace objects: persons, groups, roles, or associations. When you add the keyword
Use the use keyword once for any optional files specified in the compare command: map files,
exclude files, log files, or exception files. If more than one file type is to be used, the use keyword
should be stated once only.
The use FILETYPE FILENAME option lets you specify optional files to be used in the compare
operation. FILETYPE accepts four values:
• log
The use log FILENAME option creates a file that contains the report for the compare
operation. The compare command can be issued without identifying a log file, in which case
just a summary of the analysis is returned in the MQL window—total number of objects
analyzed, changed, added, deleted. The log file report lists exactly which objects were
analyzed and describes the differences. More information appears in the report if verbose mode
is turned on. For more information about the report, see Reading the Report.
An efficient approach is to run the compare command without a log file to see if any changes
have occurred. If changes have occurred, you could turn on verbose mode, re-run the compare
command and supply a log file to capture the changes.
• map
A map file is a text file that lists administrative objects that have been renamed since the
baseline file was created. The map file maps names found in the given baseline file with those
found in the database (where renaming has taken place). Use the map file option to prevent the
compare operation from finding a lot of changes simply because administrative objects had
their names changed. The map file must use the following format:
ADMIN_TYPE OLDNAME NEWNAME
ADMIN_TYPE OLDNAME NEWNAME
OLDNAME is the name of the object in the baseline export file. NEWNAME is the name of the
object in the current schema (the schema you are comparing against the baseline file). Include
quotes around the names if the names include spaces. Make sure you press Enter after each
NEWNAME so each renamed object is on a separate line (press Enter even if only one object
is listed). For example, if the Originator attribute was renamed to Creator, the map file would
contain this line:
attribute Originator Creator
• exception
The use exception FILENAME option creates a file that lists objects that could not be
compared. If a transaction aborts, all objects from the beginning of that transaction up to and
including the “bad” object are written to the exception file.
FILENAME is the path and name of the file to be created (log and exception files) or used (map
and exclude files). If you don’t specify a path, 3DSpace uses the directory that contains the mql.exe
file.
Verbose Mode
Turn on verbose mode to see more details in the report for changed objects/sub-objects (possibility
4 in the above description). To see these additional details, make sure you turn on verbose mode
before issuing the compare command.
When the operation finds changes to objects, verbose mode adds text as follows:
• For possibility 4a (field has been added), the keyword “new” appears followed by VALUE.
• For possibility 4b (field was deleted), the keyword “was” appears followed by VALUE.
• For possibility 4c (field was changed), the keywords “was” and “now” appear, each followed
by VALUE.
where VALUE is either the actual value (in single quotes) or a series of name/value pairs
(where the value portion of the name/value pair is in single quotes).
Here are some sample messages that would appear in the change analysis section if the compare
operation finds that an object has changed (possibility 4) and verbose mode is turned on:
field fieldType 'select' has been added.
new absoluteX '0' absoluteY '0' xLocation
'382.500000' yLocation '36.000000' width
'122.400002' height '24.000000'
autoWidth '0' autoHeight '0' border '0'
foregroundColor 'red' backgroundColor ''
fieldValue 'name' fontName 'Arial Rounded MT
Bold-10' multiline '0' editable '0'
Examples
Below are two example MQL sessions. The first MQL session shows two baseline export files
being created.
Matrix Query Language Interface, Version 9.0.0.0
Copyright (c) 1993-2000 MatrixOne, Inc.
Line <2> places the session All rights reserved.
into XML mode. All MQL<1>set context user Administrator;
subsequent export MQL<2>xml on;
commands will generate
export files in XML format. MQL<3>export program A* into file d:\enoviaV6R2011\studio\xml\program1.xml;
Line <3> exports all programs MQL<4>export person * into file d:\enoviaV6R2011\studio\xml\person1.xml;
(including wizards) that start MQL<5>quit;
with “A”.
Line <4> exports all persons.
This portion of the MQL window shows a continuation of the previous session. Here, the baseline
export file program1.xml is used for several more comparisons. The sections that follow show the
contents of the files used in the compare commands.
Line <7> performs a compare on MQL<6>verbose off;
all program objects that start with
the letter “A” but also includes a MQL<7>compare program A* from file d:\enoviaV6R2011\studio\xml\program1.xml
map file that identifies a rename use log d:\enoviaV6R2011\studio\xml\program1.log map
of one of the program objects. d:\enoviaV6R2011\studio\xml\program1.map;
See program1.map and 2 objects have been added.
program1.log. Notice that “use” is 0 objects have been removed.
only used once even though two 3 objects have been changed.
files are used (a log file and a
11 objects are the same.
map file).
compare successfully completed.
MQL<8>verbose on;
MQL<9>compare program A* from file d:\enoviaV6R2011\studio\xml\program1.xml
use log d:\enoviaV6R2011\studio\xml\program2.log map
Line <9> performs the same d:\enoviaV6R2011\studio\xml\program1.map;
compare as in Line <7> but with
2 objects have been added.
verbose mode turned on. Look at
the two reports (program1.map 0 objects have been removed.
and program2.log) to see the 3 objects have been changed.
difference between verbose off 11 objects are the same.
and on. compare successfully completed.
MQL<10>compare program A* from file
d:\enoviaV6R2011\studio\xml\program1.xml use log program3.log map
d:\enoviaV6R2011\studio\xml\program1.map exclude
d:\enoviaV6R2011\studio\xml\program1.exc;
Line <10> performs the same 2 objects have been added.
compare but adds an exclude file 0 objects have been removed.
that eliminates two program 2 objects have been changed.
objects from the analysis (thus
leading to two fewer objects
mentioned in the results). See
program1.exc and program3.log.
program1.log
Map file 'd:\enoviaV6R2011\studio\xml\program1.map' successfully read.
An exclude file was not given.
Input baseline file: 'd:\C:\enoviaV6R2011\studio\xml\program1.xml'.
Type = 'program', Name Pattern = 'A*', Workspace 'excluded'.
Start comparison at 'Wed Jun 21, 2000 2:13:49 PM EDT'.
Baseline version was '9.0.0.0'.
Current version is '9.0.0.0'.
=====================================================
====== 'program' 'Add Component (As-Designed)' ======
description has been changed.
====== 'program' 'Add Assembly (As-Designed)' ======
====== 'program' 'Add Purchase Requisition' ======
====== 'program' 'Add Event' ======
====== 'program' 'AttributeProg' ======
====== 'program' 'A' ======
====== 'program' 'A1' ======
====== 'program' 'A2' ======
====== 'program' 'Add ECR' ======
------ 'frame' 'Master Frame' ------
------ 'frame' 'Welcome' ------
------ 'frame' 'Change Type' ------
------ 'frame' 'Reason For Change' ------
width has been changed.
widget 'ReasonForChange' multiline has been changed.
widget 'ReasonForChange' validateProgram programRef has been
changed.
widget 'postECR Input1label4' fontName has been changed.
widget 'Reason For Changelabel5' widgetValue has been changed.
------ 'frame' 'Product Line' ------
widget 'Product Linelabel4' has been added.
------ 'frame' 'Change Priority' ------
------ 'frame' 'Reason for Urgency' ------
widget 'Product Linelabel4' has been deleted.
------ 'frame' 'AdditionalSignatures' ------
------ 'frame' 'Conclusion' ------
------ 'frame' 'Conclusion-Urgent' ------
------ 'frame' 'Status Feedback' ------
frame 'Change Class' has been added.
====== 'program' 'Add Assembly' ======
------ 'frame' 'Master Frame' ------
------ 'frame' 'Welcome' ------
------ 'frame' 'Make vs Buy' ------
widget 'MakevsBuy' validateProgram programRef has been changed.
------ 'frame' 'Part Family' ------
------ 'frame' 'Assembly Description' ------
------ 'frame' 'Target Parameters' ------
------ 'frame' 'Status Feedback' ------
'program' 'Add Task' mapped to 'Add Task Import'
====== 'program' 'Add Task Import' ======
------ 'frame' 'Master Frame' ------
------ 'frame' 'Welcome' ------
program2.log
Map file 'd:\enoviaV6R2011\studio\xml\program1.map' successfully read.
An exclude file was not given.
Input baseline file: 'd:\enoviaV6R2011\studio\xml\program1.xml'.
Type = 'program', Name Pattern = 'A*', Workspace 'excluded'.
Start comparison at 'Wed Jun 21, 2000 2:13:36 PM EDT'.
Baseline version was '9.0.0.0'.
Current version is '9.0.0.0'.
=====================================================
====== 'program' 'Add Component (As-Designed)' ======
description has been changed.
was 'Matrix Prof Services: Contains settings for the program to
create and connect and a new object with AutoName logic.'
now 'Matrix Professional Services: Contains settings for the program
to create and connect and a new object with AutoName logic.'
====== 'program' 'Add Assembly (As-Designed)' ======
====== 'program' 'Add Purchase Requisition' ======
====== 'program' 'Add Event' ======
====== 'program' 'AttributeProg' ======
====== 'program' 'A' ======
program1.exc
program “Add ECR”
program “Add Note”
program3.log
Map file 'd:\enoviaV6R2011\studio\xml\program1.map' successfully read.
Exclude file 'd:\enoviaV6R2011\studio\xml\program1.exc' successfully
read.
Input baseline file: 'd:\enoviaV6R2011\studio\xml\program1.xml'.
Type = 'program', Name Pattern = 'A*', Workspace 'excluded'.
Start comparison at 'Wed Jun 21, 2000 2:13:28 PM EDT'.
Baseline version was '9.0.0.0'.
Current version is '9.0.0.0'.
=====================================================
====== 'program' 'Add Component (As-Designed)' ======
description has been changed.
was 'Matrix Prof Services: Contains settings for the program to
A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | Y
179
approve businessobject 98 C
attribute case-sensitive
assigning to object types 46, 63 adaplets 137
assigning to relationships 46 attribute ranges 138
defined 46 file names 137, 138
defining 46 match 137
multiple local attributes 49 Oracle setup 134
multi-value 51 policy 137
name 46, 63 changevault
ranges 51, 138 setting for the system 138
types 47 channel
adding 128
B defining 128
backup strategy 148 name 128
baseline checking out files 96
creating 165 clauses
use to compare schema 166 defined 24
best-so-far (BSF) object syntax 24
for major/minor revisioning 78 command
browser adding 120, 124
defining cues 109 defining 124
Business 9 name 120, 124
business object commands
access (locking) 97 keyword 25
approve 98 comments
checking out files 96 entering 24
copies vs. revisions 91 syntax 24
commit transaction 34
demoting 102
disabling 99 common schema. See Application Exchange
enabling 100 Framework.
compare
grouping into set 107
ignore 98 verbose mode 169
locking 97 compare command
major/minor revisioning 92 examples 171
modifying state 98 introduced 166
name 86, 87 comparing schema
not analyzed in compare 166 creating baseline 165
override 101 examples 171
ownership 81 getting more details 169
prerequisite objects 86 introduced 164
promoting 101 objects not included 166
protecting (locking) 97 reading the report 168
reject 99 with baseline 166
relationship prerequisites 86 compile program 113
revising 90 connect command
revision designator 87 preserve 94
type 87 connections
unlocking 97 introduction 103
unsign signature 99 constraint
viewing definition 89, 104 setting for the system 139
continue keyword 28
Index 181
H M
history macro
setting for the system 141 for object name 126
for object revision 126
for object type 126
I for select expressions 126
ID major/minor revisioning
object 88 best-so-far object 78
ignore businessobject 98 business objects 92
implementing locks in applications 89 relationships 77
implicit manual, how to use 11
transactions 34 map file
type characteristics 66 compare command 167
import match 137
Matrix Exchange Format files 160 matchcase 137
properties 161 MatrixOne applications
servers 160 documentation 11
strategy 163 items in 9
workspace 160 menu
XML files 160 adding 127
import 160 defining 127
index 149 name 127
attribute with rule 150 migrating
selects 151 databases 163
validate 151 files 163
insert program 113 revision chains 164
instances of relationships 103 modification date
interface preserve 94
adding 65 modifying
defined 65 business object state 98
defining 65 MQL
name 65 parameterized commands 29, 43
multiple local attributes 49
K MX_DECIMAL_SYMBOL 140
keyword
defined 25 N
in commands 25 name macro 126
syntax 25 naming a business object 87
NLS_LANG 140
L non-abstract types 67
large files 96
least privilege 44 O
lifecycle 69 object ID 88
locking objects in applications 89 object reserve 89
log file object type, assigning attributes 46, 63
compare command 167 OID. See object ID
report for compare command 168 option, in commands 25
Oracle 140
casesensitive setting 134
constraints 139
Index 183
rule policy 70
adding 80 published 71
attribute and index 150 revisionable 71
name 80 versionable 71
run statement 28 statements
running scripts 28 clauses 24
values 24
structure
S copying 94
schema deleting 94
comparing 164 listing 94
comparing with baseline 166 printing 94
creating baseline for 165 Studio Customization Toolkit
scommands setting history logging off 141
options 25 suite
script Also see application.
comments 24 syntax
creating definitions 32 clauses 24
running 28 comments 24
select keywords 25
expression macros 126 options 25
index 151 quotes 25
server rules 24
importing 160 statements 24
servlet ADK Tcl 40
required skills 6 values 24, 25
set system decimal symbol 140
adding 107 system settings
defined 107 printing 143
defining 107 system-wide settings 134
name 107
vs. connection 107
set system 134 T
casesensitive 134, 135 table
set transaction 34 adding 130
shell command defining 130
described 28 name 131
signature Tcl
approve 98 command syntax 40
ignore 98 temporary query 106
override requirement 101 tidy
reject 99 system setting 142
unsign 99 Tracing
signatures 137 index 151
SQL Server transaction
case sensitivity 135 control 34
stale relationships 143 explicit 34
start transaction 34 implicit 34
state statements 34
changing 73 transaction boundaries
defining 70 extending 34
number required 70 type
U
unsign businessobject signature 99
update set 138
user access
policy 70
V
validate index 151
validate unique 135
validation
database 143
levels 143
value
defined 24
syntax 25
verbose
compare 169
verbose
introduced 28
version 28
viewing
business object definition 89, 104
visual cue
adding 109, 119
name 109, 110, 119
W
web form 132
webreport
XML result limit 120
white list input validation 44
working on legacy data 88
workspace
importing 160
workspace user USER_NAME clause 128, 129
Index 185
186 MQL Guide