qwertyuiopasdfghjklzxcvbnmqwertyui

opasdfghjklzxcvbnmqwertyuiopasdfgh
jklzxcvbnmqwertyuiopasdfghjklzxcvb
Product Lifecycle Management
nmqwertyuiopasdfghjklzxcvbnmqwer
tyuiopasdfghjklzxcvbnmqwertyuiopas
Quick Tips To

dfghjklzxcvbnmqwertyuiopasdfghjklzx
eMatrix Version 10.6

cvbnmqwertyuiopasdfghjklzxcvbnmq
Matrix Query Language
&
wertyuiopasdfghjklzxcvbnmqwertyuio
Tool Command Language

pasdfghjklzxcvbnmqwertyuiopasdfghj
klzxcvbnmqwertyuiopasdfghjklzxcvbn
mqwertyuiopasdfghjklzxcvbnmqwerty
uiopasdfghjklzxcvbnmqwertyuiopasdf
ghjklzxcvbnmqwertyuiopasdfghjklzxc
vbnmqwertyuiopasdfghjklzxcvbnmrty
uiopasdfghjklzxcvbnmqwertyuiopasdf
ghjklzxcvbnmqwertyuiopasdfghjklzxc
vbnmqwertyuiopasdfghjklzxcvbnmqw
ertyuiopasdfghjklzxcvbnmqwertyuiop
 Compiled by: Ashish Devta

Table of Contents

1 Introduction..............................................................................................................5
1.1 MQL Command Syntax:.................................................................................5
1.2 MQL Commands:...........................................................................................5
2 Extracting Information from Database................................................................6
2.1 Identifying Business objects:.........................................................................6
2.2 Basic MQL Commands:.................................................................................6
2.2.1 List..............................................................................................................7
3 Create and Modify Commands.............................................................................10
3.1 Add:.............................................................................................................10
3.2 Copy:............................................................................................................10
3.3 Delete:.........................................................................................................10
3.4 Modify:.........................................................................................................10
3.5 Connect:.......................................................................................................11
3.6 Promote/Demote:........................................................................................11
4 Tool Command Language (TCL)..........................................................................11
4.1 Overview......................................................................................................11
4.2 Variables......................................................................................................11
4.3 Grouping......................................................................................................12
4.4 Variable Commands.....................................................................................14
5 Matrix Program Objects........................................................................................15
5.1 Introduction..................................................................................................16
5.2 Immediate Programs...................................................................................16
5.3 Deferred Programs.......................................................................................16
5.4 Downloadable Programs..............................................................................16
5.5 Piped Programs............................................................................................16
5.6 Pooled Programs..........................................................................................17
6 Runtime Program Environment...........................................................................17
6.1 RPE Commands............................................................................................17
6.2 Global RPE...................................................................................................17
6.3 RPE and Macros...........................................................................................18
6.4 Program Features........................................................................................18
7 String, List Processing and Arrays......................................................................19
8 Control Flow.............................................................................................................33
9 Exception Handling..................................................................................................35
10 Event Triggers..........................................................................................................36

Page 2 of 32
 Compiled by: Ashish Devta
11 Procedures...............................................................................................................37
12 File System...............................................................................................................38
13 Glossary....................................................................................................................41

Page 3 of 32
 Compiled by: Ashish Devta

1 Introduction
This write up is intended to facilitate quick learning of MQL and TCL. The document covers
Matrix Query and Tool Command Languages in detail. Also, it provides syntax and
examples per command.
MQL acts as an interpreter for Matrix and can be used in one of the three modes:
1. Interactive Mode
2. Script Mode
3. Tool Command Mode

1.1 MQL Command Syntax:

 MQL commands are entered as free form list of words separated by one or more
blanks, tabs, or newlines.
 Command lines end with a (;) or two consecutive newlines.
 Command names are not case sensitive.
 Values are case sensitive.

1.2 MQL Commands:

a) verbose [on/off]:
When set to “on” Matrix provides additional information about commands
executed successfully or unsuccessfully in Matrix.
When set to “off” only error messages and high priority system messages are
provided.
b) Context:
Set context person creator vault “eService Production”;
If context is not set, the default user is guest is assigned the context and the
home vault is Administration.
c) Comments:
Text appearing after a hash symbol (#) is seen as a comment.
# This is a comment line
List bus; # list business objects

d) Tcl mode:
To enter Tcl mode while in MQL command editor enter the command:
tcl;
The command editor prompt changes to:
%
To exit the Tcl mode enter the command:
Page 4 of 32
 Compiled by: Ashish Devta
exit;
e) Executing MQL scripts:
Run FILE_NAME [continue];
The run command enables to run a script file. The continue keyword allows
the script to run without stopping when an error occurs.
Following is the command to run the script file “sample.mql”:
Run “C:/sample.mql” continue;

2 Extracting Information from Database

2.1 Identifying Business objects:

Business Objects can be identified by their Object Type, Name and Revision
combination or by their Business Object ID.
BO_NAME = Type Name Revision [in vaultname]
Example:
BO_NAME = 43542.65478.23456.23543
2.2 Basic MQL Commands:
 List
 Print
 Expand
 Query
 Evaluate Expression

2.2.1 List
This command is used to view all the list of business and admin objects.
Syntax:
list item;
Example:
list type;
list attribute A*;
list bus vault “eService Production”;
list person;
2.2.2 Print
This command is used to retrieve information about a single business or admin
object.

Page 5 of 32
 Compiled by: Ashish Devta
Syntax:
print item name;
For Business Objects:
Print bus BO_NAME
[selected | select [ fields ] ]
[dump separator ]
[output FILE_NAME ];
For Admin Objects:
Print adminitem NAME
[ selected | select [ fields ] ]
[ dump separator ]
[ output FILE_NAME ];

Examples:
Print bus AgilentPart abc001 1 select attribute[APDescription];
Print type “AgilentPart”;
Print bus AgilentPart abc002 1 select attribute[APDescription]
attribute[APWeight] dump | output “C:/temp.txt”;

2.2.3 Expand
This command is used to view connected business objects from a starting object.
Syntax:
Expand bus BO_NAME
[to | from] // specify direction to expand from or to starting object
[Relationship PATTERN]
[type Pattern]
[recurse to [all | N] ] // expands connected objects at deeper levels
[select bus FIELDS [where]]
[select rel FIELDS [where]]
[into | onto set SETNAME]
[dump SEPARATOR]
[output FILENAME]
[terse] // Output object IDs instead of Type, Name, Revision
[limit N]; // Limit output to number of objects specified

Page 6 of 32
 Compiled by: Ashish Devta
2.2.4 Query
 A query is a search of the Matrix database for objects that meet the specified
criteria.
 Queries are defined, named and saved to the database based on the query
context.
 To produce results the query object must be evaluated.
 Temporary queries are not saved to the database.

Syntax:
a) This syntax is to add a query object to the database
Add query query_name
[ businessobject Type Name Revision ]
[ owner user_name ]
[ vault Vault_name ]
[ where query_expr ];
The below syntax is to evaluate an existing query object:
Evaluate query query_name
[ over set Name ]
[ into|onto set Name ]
[ limit VALUE ]

b) This command is to evaluate a temporary query object

Temp query businessobject Type Name Revision
[!expand]
[vault VAULT_NAME]
[owner USER_NAME]
[limit VALUE]
[where]
[select]
[dump SEPARATOR]
[output FILE_NAME]

2.2.5 Evaluate expression

Expressions can execute against a collection(s) of business objects, a single
business object or a single connection.
Syntax:

Page 7 of 32
 Compiled by: Ashish Devta
Evaluate expression EXPRESSION
on {COLLECTION} {BUSINESSOBJECT} {CONNECTION}
[dump [CHAR] ]
[recordseparator SEPARATOR];

MX_CURRENT_TIME -- A parameter representing the current time of the Matrix

database server, measured in milliseconds.

3 Create and Modify Commands

MQL allows creating new and/or modifying administrative as well as business objects
in the Matrix schema.

3.1 Add:
Add businessobject TYPE NAME REVISION
[description DESCRIPTION]
Policy POLICY
[vault VAULT]
[ATTRIBUTENAME VALUE];
3.2 Copy:
Copy businessobject BO_NAME to Name Revision [ITEM {ITEM}];
3.3 Delete:
Delete bus BO_NAME;
3.4 Modify:
Modify bus BO_NAME
[Modify_ITEM value];
3.5 Connect:
Connect bus BO_NAME
Relationship RELATIONSHIP_NAME
[ to | from ] BO_NAME
[ATTRIBUTE_NAME VALUE…];
3.6 Promote/Demote:
Promote bus BO_NAME;
Demote bus BO_NAME;

Page 8 of 32
 Compiled by: Ashish Devta
4 Tool Command Language (TCL)
4.1 Overview
 Tcl is a simple scripting language for controlling and extending applications.
 Tcl is an interpreted “Shell” language.
 Tcl is supported in multiple platforms(UNIX,DOS,Windows,OS/2,NT)

Tcl provides the following capabilities.

 Variables, Arrays and Lists
 String Manipulation.
 Flow Control
 Procedures.
 File Access.
 Process Execution

General Syntax:
 Tcl scripts contain one or more tcl commands separated by new lines or
semicolons.
 The first word in a Tcl command is the name of the command. The rest of the
words are the command arguments.
 Tcl commands and variables are case sensitive

4.2 Variables
 All variables are type string.
 All variables and values are case sensitive.
 Variable names and values can be arbitrary string of characters.
Example:-
set 456*99-33 100;
In the above statement “456*99-33” is a variable name and value 100 is assigned to
it.
 Declaration is not required.

Assignment:-
Values are assigned to a variable with the set command.
Example:-
set sMyvar “Hard Disk”;
Set iCount 23;
Access Variable Values:
Dollar sign($) invokes variable substitution.
Example:-
puts iCount; #Prints 23
Special Variable Substitution:
Page 9 of 32
 Compiled by: Ashish Devta
Use ${} for variable substitution.
Example:-
puts ${iCount}-34; #Prints 23-34
Command Substitution:
Square brackets invoke command substitution. Text inside the brackets is evaluated
as a separate Tcl script.
Example:-
set iResult [expr 2+2];
The [] cause the text inside to be executed. The result is substituted for [] and the text,
and assigned to the variable.

4.3 Grouping
 Grouping is used to combine multiple words into one argument for a command.
 Grouping is always performed before substitution when Tcl parses a command.
 Tcl makes a single pass through a statement to determine groups.
 Two types of grouping characters
a) Double Quotes – allow substitutions to occur.
b) Curly Braces – prevent substitutions in a group.

Double Quote Grouping:

 Variable, command and character substitutions occur as usual within double quotes.
 Any spaces, newlines and semicolons found between double quotes are considered
part of the same command argument.
Example:-
1) set iNum 99;
puts “The value of iNum is $iNum”;
The above command would return the below output:
 The value of iNum is 99.

2) puts “Some text; \n more text”;

The above command would return the below output:
 Some text;
more text
Brace Grouping:
 Variable, Command and character substitutions DO NOT occur within brace
quoting(unless the braces are contained within double-quotes).
Page 10 of 32
 Compiled by: Ashish Devta
 Braces disable all character substitution except backslash-newline.
 Useful to defer evaluation in procedures and certain Tcl commands.

Example:-
1) set iCount 99;
puts {The value of iCount is $iCount};
The output for above command is:
 The value of iCount is $iCount
2) puts {hello \n hello; $more [text]};
Output for above command is as below:
hello \n hello; $more [text]

Note: - All special characters (space, \n, [, ], and ;) lose their meaning and are printed
as normal characters.
4.4 Variable Commands
Variable commands work directly with Tcl variables to modify the value of the variable
based on the command type. We have already seen the use of set command. The rest
commands are the following:
1) incr
2) append
3) unset
4) expr

1) incr:
Adds increment to the contents of variable and places the resulting value in variable.
Default increment value is 1.
Syntax:
Incr varName ?increment?

Example:
set iSize 2;
incr iSize 2; #increments value of iSize by two.
2) append:
Concatenates all the vales and appends them to the end of the variable, creating the
variable if it doesn’t exist.
Syntax:

Page 11 of 32
 Compiled by: Ashish Devta
append varName value ?value …?
Example:
Append sPart Memory “” 128 MB;
puts $sPart;
 Memory 128MB.
3) unset:
Removes the specified variable and the value assigned to it from memory
Syntax:
unset varName ?varName …?
Example:
Unset iSize sName; #iSize and sName variable are deleted.
Note: -Once a variable is removed the value assigned to that variable no longer exists.
When a Tcl program ends the variables and all values declared in the program are also
removed from memory.
4) expr:
Concatenates all the arguments and evaluates them as an expression.
Syntax:
Expr arg ?arg arg …?
Example:
Expr (10/2) + 3
The above expression after evaluation returns the following output:
8 #expression is evaluated and returned as a string.
5 Matrix Program Objects
Matrix program objects are used for a variety of purposes including.
 Format definitions for edit, view and print commands
 As Action, Check or Override event triggers or as actions or checks in the
lifecycle of a policy.
 To run as methods associated with certain object types.
 As toolset programs executed from the matrix toolbar

5.1 Introduction

Matrix programs are stored in the matrix schema as an administrative object. Program
objects are created using matrix business modeler or can be created using MQL
commands.

There are 3 types of programs

Page 12 of 32
 Compiled by: Ashish Devta
 MQL- MQL command access, supports Tcl commands
 External – Executes programs outside of matrix environment.
 Java – Supports Java Programming Objects (JPO).

5.2 Immediate Programs

Program is executed within the current database transaction.
5.3 Deferred Programs
Programs will execute outside of the current matrix database transaction. Keep in
mind few points.
 Deferred programs execute only if the original transaction is successful
 A failure in the deferred program does not undo the original transaction.

5.4 Downloadable Programs

When a program is marked as downloadable, the code is downloadable to web client
and executed locally using local MQL/Tcl program files.
Note: downloadable programs must be set as deferred.

5.5 Piped Programs

Piped programs are run as a separate process, but the launching thread in the core
acts as an “mql command” service.
When a piped is checked, external is automatically selected. The piped service is not
available to JPO or MQL program objects. Execution may be immediate or deferred.
A piped program cannot be downloadable.
5.6 Pooled Programs
A non-pooled MQL/Tcl program causes a Tcl interpreter to be invoked and then
closed each time the program runs in a session.
A pooled program uses an interpreter “pool” that is shared for a session to increase
performance.

6 Runtime Program Environment

When a Matrix program completes execution all Tcl variables that have been set are
released from memory. To retain specific values across programs require the use of the
RPE.
 The (RPE) is the mechanism used to pass and collect information between
program objects within the same instance of matrix.
 The (RPE) contains named programs environment variables that store string
values.
 Information can be passed between matrix programs.

Page 13 of 32
 Compiled by: Ashish Devta

6.1 RPE Commands

The following MQL commands must be used to manipulate RPE variables.
set env [global] NAME VALUE;
get env [global] NAME;
unset env [global] NAME;
list env;
exists env [global] NAME;
listnames env [global];

6.2 Global RPE

Matrix maintains two memory spaces for RPE variables/values.
 Non-Global variables are deleted when the program from which they were
issued ends.
 Global variables persists for the life of a matrix session or when they unset or
cleared using RPE command. Use global key word to access global space.

6.3 RPE and Macros

All matrix macros are also available in the RPE using the macro variable name.
Macro RPE Variable
${TYPE} mql get env TYPE
${USER} mql get env USER
${OBJECTIVE} mql get env OBJECTID

6.4 Program Features

Program features allow matrix programs to provide feedback to a user, provide
feedback to Matrix, change user context and nest MQL/Tcl commands.
mql notice
mql warning
mql error

6.4.1 Push Context

For programs that need to temporarily change context:
Syntax:
push context
user NAME
Page 14 of 32
 Compiled by: Ashish Devta
password PASSWORD
vault VAULT #Pushes context to stack.

6.4.2 Pop context

Returns last context on stack
Syntax:
pop context

6.4.3 INI settings

Matrix.ini variable MX_RESTORE_CONTEXT
If TRUE original context is restored at program conclusion else pushed context
remains changed.

6.4.4 Nesting Programs

Executing another Matrix program from a program
Example:-
execute program PROGRAM_NAME
When the executing program finishes control passes back to the calling program.
We can also execute methods on a business object using the following syntax:
execute businessobject BO_NAME method METHOD_NAME;

6.4.5 Executing Programs from command line

Executing a program from the OS command line:
matrix.exe –mql –c “execute program NAME”

6.4.6 Creating a method

Methods are program objects that are attached to a business type. If we attach the
method to an abstract type then all derived types under that abstract type will be
allowed to access the method.

7 String, List Processing and Arrays

I. String
a) string length:
Returns the length of the string.
Syntax:

Page 15 of 32
 Compiled by: Ashish Devta
string length string_name;
Example:-
If we want to find the length of the string “ematrix” then the command is:
string length “ematrix”;
In this case the above command returns output as below.
7
b) string index:
Returns the charindex character of string or an empty string if it doesn’t exist.
Syntax:
string index string_name charIndex
Example:-
When we want to find the character the 6th character in the string “Hello World”:
string index “Hello World” 6;
This command returns the output (W) as below
W #index start with 0

c) string range:
Returns the substring of string that lies between the first and last indices.
Syntax:
string range string_name first last
Example:-
string range “A test string” 7 end
string #end indicates end of the string.

d) string first:
Returns the first occurrence where string1 is found in string2 or -1 if it is not found.
Syntax:
string first string1 string2
Example:-
1) if we consider string1 as “!” and string2 as “Help!Me” then to find the
first occurrence of string1 in string2 then the following query can be
used:
string first “!” “Help!Me”
This query returns an output as below:
4 #index start with 0
Page 16 of 32
 Compiled by: Ashish Devta
2) if we consider string1 as “a” and string2 as “Help!Me” then to find the
first occurrence of string1 in string2 then the following query can be
used:
string first “a” “Help!Me”
This would return -1.
-1 #because “a” is not found in the second string.
e) string last:
Returns the last position where string1 is found in string2 or -1 if it is not found.
Syntax:-
string last string1 string2
Example:-
If we consider string1 as “!” and string2 as “Help!Me” then to find the last
occurrence of string1 in string2 then the following query can be used:
string last “!” “Help!Me”
This query returns an output as below:
7 #index start with 0
f) string compare:
Compares the string and returns -1, 0 or 1 if string1 is less than, equal to, or greater
than string2.
Syntax:-
string compare string1 string2;
Example:-
1) string compare “First” “Second”
-1 #because “First” is less than “Second”.
2) string compare “Second” “First”
1 #because “First” is less than “Second”.
3) string compare “First” “First”
0 #because both string are equal

g) string match:
Returns 1 if pattern matches string_name and 0 if it doesn’t.
Syntax:-
string match pattern string_name
Example:

Page 17 of 32
 Compiled by: Ashish Devta
1) if we have “*test” as the pattern and it is being matched with “this is a
test” then below is the respective query and output:
string match “*test” “this is a test”
1 #because pattern is matched.
2) if we have “*test” as the pattern and it is being matched with “this is a
sample” then below is the respective query and output:
string match “*test” “this is sample”
0 #because pattern does not match.

h) string tolower:
Returns a lowercase version of string.
Syntax:
string tolower string_name;
Example:-
string tolower “A Test String”
a test string

i) string toupper
Returns the string with all characters in upper case.
Syntax:
string toupper string_name
Example:-
string toupper “a test String”
A TEST STRING

j) string trim:
Trims characters found in chars from each end of the string. Default is white space.
Syntax:
string trim string ?chars?
Example:-
string trim “ A test string !!!!” “ !”
A test string #removes “!” start from each ends from the

k) string trimleft:

Page 18 of 32
 Compiled by: Ashish Devta
Trims characters found in chars from the left end of the string. Default is white
space.
Syntax:-
string trimleft string ?chars?
Example:-
string trimleft “ A test string !!!!” “ !”
 A test string !!!! #remove left side characters only.
l) string trimright:
Trims characters found in chars from the right end of the string. Default is white
space.
Syntax:-
string trimright string ?chars?
Example:-
string trimright “ A test string !!!!” “ !”
 A test string #remove right side characters only.
m) regexp:
Returns 1 if regular expression exp matches all or part of string. Otherwise returns 0.
Syntax:
regexp exp string_name
Example:
The below query checks whether the expression “does|match$” matches the
string “Does this match”. Since the expression matches the string it returns 1.
regexp “does|match$” “Does this match”
1
n) regsub
Syntax:-
regsub exp string_name substitute varName
Copies string_name to varName. While copying, if a match for exp is found, it is
replace with substitute. The number of substitutions is returned.

Example:-
regsub “match$” “match test – does this match” “**replaced**” sStr;
1 #returns no. of substitutions.
puts $sStr
match test – Does this **replaced**

Page 19 of 32
 Compiled by: Ashish Devta
o) format:
Syntax:
format formatstring ?value value …?
Returns a string similar to formatString, except that % sequences have been
replaced by the given values.
Example:-
format “The %s number %d is %x in %s decimal 23 23 hex
The decimal number 23 is 17 in hex.
p) scan:
Parses the string according to the format and assigns values to varNames. Returns
number of scanned items.
Syntax:
scan string_name format varName ?var…?
Example:-
scan “Decimal 23 = 17” “%s %d = %x” a b c
3
II. List
 Lists are collections of words separated by white space.
 Lists structures allow you to work with matrix data easily and to parse specific data
from a result.
 A list is an ordered set of items containing any string value separated by white
space. Lists can be nested to any level and are useful to process information
returned from MQL commands.
 Lists are considered a special kind of string in Tcl. Rather than dealing with
collections of characters, lists deal with collections of elements, which become
very useful with the result of MQL commands from matrix.

a) list:
Syntax:
list ?value1 value2 ..?
Creates a list from the value arguments and returns it.
Example:-
set lComps [list Memory Mouse “System Box”]
Memory Mouse {System Box} #list is created and stored in lComps.
b) concat:
Syntax:
concat ?list1 list2 …?

Page 20 of 32
 Compiled by: Ashish Devta
Concatenate multiple lists and returns the resulting list.
Example:-
concat [list a b c d] [list e f g h]
a b c d e f g h
c) lappend:
Syntax:-
lappend varName value1 ?value …?
Appends all the values as a list to the list varName. Creates varName if it
doesn’t exist.
Example:
set lComps [list memory mouse];
lappend lComps Monitor
memory mouse Monitor

d) lindex:-
Syntax:-
lindex list index;
Returns the index item from the list varName(0 is the first item).
Example:-
set lComps [list memory mouse Monitor];
lindex $lComps 2
Monitor
e) length:
Syntax:
llength list
returns the number items in the list.
Example:-
set lComps [list memory mouse Monitor];
llength $lComps
3
f) lrange:
Syntax:
lrange list first last
returns the list of items first through last of the list.

Page 21 of 32
 Compiled by: Ashish Devta
Example:-
set lComps [list memory mouse Monitor];
lrange $lComps 0 1
memory mouse

g) linsert :
Syntax:
linsert list index value1 ?value2 …?
Returns a list consisting original list with all the values inserted as list items
before the indexed item (index starts with 0).
Example:-
set lComps [list memory mouse Monitor];
linsert $lComps 1 Ram
memory Ram mouse Monitor
Note:- it wont add item permanently to the list.

h) lreplace :
Syntax:
lreplace list first last ?val1 val2…?
Returns the list with items first through last of list replaced with values
Example:-
set lComps [list memory mouse Monitor];
lreplace $lComps 2 2
memory mouse

i) lsearch :
Syntax:
lsearch ?-glob ?-exact ?-regexp? list pattern
Returns the index of the first item in list that matches pattern according to the
specified technique(-1 if there are no matches). Index starts with 0.
Example:-
set lComps [list memory mouse Monitor];
lsearch –glob $lComps *s*
1 #pattern is matched in “mouse”
j) lsort :
Page 22 of 32
 Compiled by: Ashish Devta
Syntax:-
lsort ?options?list
Sorts the list based on the specified options and returns it. Options include –
ascii, -integer, -real, -dictionary, -increasing, -decreasing –index x, -command
cmd.
Example:-
set lComps [list memory mouse Monitor];
lsort –ascii $lComps
Monitor memory mouse

k) split:
Syntax:
split string_name ?splitChars?
Splits the string at each instance of splitChars and returns a list.
Example:-
split [mql list group] \n
Result:
The string is split at each instance of the new line character and the
resulting list is returned.

l) join :-
Syntax:
join list ?joinString?
Concatenates all the list items placing joinString between them and returns
the resulting string.
Example:-
join [list a b c d e] " | "
a | b | c | d | e #joins all list items with symbol “|”.

III. Arrays
Arrays are simply collections of items in which each item is given a unique index by
which it may be accessed.
 Tcl arrays consists of a collection of name and value pairs.
 Array variables can be used anywhere simple variables are used.
 Array indices can be any string, though space characters should be avoided.
Page 23 of 32
 Compiled by: Ashish Devta
 Unlike other languages Tcl arrays are not declared and are not presized with
dimension or limit statement.

Example:
set person_info(name) “Fred Smith”
set person_info(age) “25”
set person_info(occupation) “soft engg”
foreach thing {name age occupation} {
puts “$thing == $person_info($thing)”
}
name == Fred Smith
age == 25
occupation == Sales Rep
Array command options
Commands that are used to access and manipulate arrays in Tcl.
1. array exists
2. array size
3. array names
4. array set
5. array get

a) array exists:
checks if an array exists. Returns 1 if the array variable exists.
Syntax:
array exists arrayName.
b) array size:
Syntax:
array size array_name
Returns the number of name-value pairs in the array.
c) array names:
Returns each name in the array.
Syntax:
array names array_name
Example:-
array names person_info;

Page 24 of 32
 Compiled by: Ashish Devta
name age occupation
d) array set:
Syntax:-
array set arrayName list
Creates an array named arrayName from the elements in the list.
Example:-
array set aPerson {Name Joe job Boss}
e) array get:
Syntax:-
array get arrayName
returns each name-value pair in the array as list.
Example:-
array get aPerson
Name Joe job Boss
f) env Array:-
Tcl maintains an internal array named env which allows access to the
operating system environment variables.
Example:-
array get env;

g) info:-
The info command provides information about various internals of the Tcl
interpreter. It is used to display information about Tcl commands, variables,
procedures, machines hostname, etc.
Syntax:-
info options ?arg1 arg2 …?...
Example:-
into vars s*
info exists sPart

8 Control Flow
Control Flow commands in Tcl allow for conditional testing of variables, looping and
error handling.
a) If:-
Syntax:-

Page 25 of 32
 Compiled by: Ashish Devta
if test1 body-1 ?elseif test2 body-2 elseif …?
?else body-N
If test1 evaluates to nonzero, then body-1 is evaluated, else if test evaluates
to nonzero, then evaluate body-2. if none of the tests evaluate to nonzero,
evaluate body-N
b) switch:-
Syntax:-
switch ?options? string {
value body
?default body …?
}
Evaluates the body of the first value that matches string. Options include –
exact, -glob, -regexp.
c) for:-
Syntax:-
for initialization test re-init body
Evaluates initialization Tcl command to establish starting values. The test
expression is then evaluated. While the expression is non-zero, The body
commands are executed. The re-init commands are evaluated at the end of
each loop cycle.
Example:-
for {set iNum 0) {$iNum<3} {incr iNum} {
puts $iNum
}
0
1
2

d) while:-
Syntax:-
while condition body
Evaluates body as a Tcl script while test evaluates to nonzero.
Example:-
set iNum 0
while { $iNum <=4 } {
puts $iNun;
Page 26 of 32
 Compiled by: Ashish Devta
incr iNum 2;
}
0
2
4

e) foreach:-
Syntax:-
foreach varName list body
For each item in list, varName is set to the value of that item and body is
evaluated as a Tcl script.

Example:-
foreach sRole [ split [mql list role] \n ] {
puts [ mql print role $sRole \
select name person dump ]
}
Result:-
Prints out each role and persons in each role.

9 Exception Handling
Exception can be caught by Tcl scripts to allow for recovery and better error
reporting. It is desirable to handle common error situations so that a program can
end gracefully or user has the chance to correct a mistake.
Commands:-
The following commands are used to manipulate exceptions.
1. catch.
2. error.
a) catch:-
Syntax:-
catch command ?varName?
the catch command is executed and any exceptions are caught the returned from
the catch command is a code indicating whether the command caused an
exception. If there is an exception, the error message is placed in varName.
Example:-
catch { mql print type Mousx } sMessage
Page 27 of 32
 Compiled by: Ashish Devta
1
puts $sMessage
Error: #190068: print type failed System Error: #1500178: business
type ‘Mousx’ does not exist
b) errorCode, errorInfo:
Reserved Tcl variables contain information on the last error that occurred
 errorCode returns the error code returned from a procedure.
 errorInfo returned the error message text.

c) error:-
Syntax:-
error message ?ifo? code?
Generates an error with the specific error message, aborts the current Tcl script,
and places information into the errorInfo variable and code into the errorCode.
Example:-
Error “Program has caused an error to occur”
Result:-
An error is generated, the error message is displayed, and Tcl script is aborted.

10 Event Triggers
Triggers are programs that are used to validate, extent or replace the current
functionality of Matrix. They allow customized implementations of Matrix
applications. Programs are attached to events in business objects, relationships and
policy states.
Trigger Program Types:
1) Check Triggers:-
The check trigger executes before any of the normal system code that carries
out the recognized event has a chance to execute. It can be used to perform
pre-event processing in anticipation of the event. A check trigger can block
the event from actually occurring, aborting the event transaction, which
means that no other trigger programs are executed. This is considered a
“hard block”.

2) Override Trigger:-
The override trigger executes after the check trigger and before the
recognized event has a chance to execute. It can be used to perform pre-

Page 28 of 32
 Compiled by: Ashish Devta
event processing. It can be replaced the normal event processing, with an
alternate event, in effect performing a “soft block” on the event.
3) Action Trigger:-
The action trigger executes after the event transaction is committed. An
action trigger is only executed if a check trigger has not performed a hard
block.
Exit Codes:-
 Check Triggers block an event by returning a non-zero value to Matrix.
 Override Triggers replace the current event by returning a non-zero valute to
matrix.
 Action triggers ignore the return value.
Note:- Tcl programs return a value to Matrix using the “exit” command.

Disabling Triggers:
To disable triggers per MQL session.
trigger off; #disable all trigger programs
trigger on #Enable all trigger programs.
Note:- User must be a Matrix System Administrator to execute this command.

11 Procedures
A procedure is a command that is implemented with a Tcl script. Procedures allow
the developer to reuse code.
 Variable created within procedure are local to that procedure.
 Procedures are created using “proc” command and called using the name of
the procedure.
a) proc command:
Syntax:-
proc proc_name argList body
Creates or replaces a procedure called proc_name, with a list of
arguments(argList) and the Tcl script to evaluate when the procedure is
called(body).
Example:-
proc pMyPrint{ sName } { puts $sName }
b) Default Arguments:-
To specify default arguments provide the argument name and default value.
proc pAddOrder { sType sName sReve { sPol “Order” } }
{

Page 29 of 32
 Compiled by: Ashish Devta
mql add bus $sType $sName $sRev policy $sPol
}
12 File System
Following is the list of commands used to perform any kind of file operations.
a) open:
Syntax:
open file_name ? access_mode?
Opens file named “file_name” in “access_mode” mode, default mode is read.
Example:-
open file “c:/file.txt”
file64
The File is opened for read access and file id is returned.
b) gets:
Syntax:-
gets fielded ? varName ?
reads the next line from field, discards the newline.

Example:-
gets file64 sText
15
Reads a line of text from file into sText and number of bytes read is returned.
c) read:
Syntax:-
1. read fileId numBytes
Reads and returns the next numBytes bytes of data in fileId.
Example:-
read file64 50
this is 50 bytes of data from file.
2. read ?-nonewline ?FileId
Reads and returns the rest of the data in fileId, disregarding the final newline
if nonewline is specifed.
Example:-
file file64
(remaining data in the file is returned here)

Page 30 of 32
 Compiled by: Ashish Devta
d) eof:
Syntax:-
eof fileId
This returns value 1 if the file pointer is at end of the file with the id fileId. Otherwise
returns a 0.
Example:-
eof file64
1

e) tell:
Syntax:-
tell fileId
Returns the current access positions for fileId.
Example:-
tell file64
 23
f) seek:
Syntax:-
seek fileId offset ? origin ?
Sets the access position within fileId to be offset bytes from origin. Origin may be
start, current, or end. Default is start. Empty string is returned.
Example:-
seek file64 50 start
seek file64 -50 end
g) puts:
Syntax:-
puts ? –nonewline ? fileId ?string
Writes a string to fileId and appends a newline character, unless –nonewline is
specified.
Example:-
open “c:/text.txt” a
file64
puts “this is a testring message” file64
writes string to the fileId and returns empty string.

Page 31 of 32
 Compiled by: Ashish Devta
h) flush:
Syntax:-
flush fileId
writes out any buffered output for this file.
Example:-
flush file64;
i) close:
Syntax:-
close fileId
Closes the file designated by fileId.
Example:-
close file64

13 Glossary

MQL Matrix Query Language

TCL Tool Command Language

JPO Java Program Objects

RPE Runtime Program Environment

Page 32 of 32