Tcl Clause

MQL print, list, expand, and temp query commands that include selects accept an optional tcl clause to signal that results should be returned in Tcl list format. Use the Tcl clause after the Dump clause (if used) and before the Output clause to return select results in Tcl list format. This output from MQL select commands is parsed using the built-in list handling features of Tcl.

This page discusses:

General Usage

Logic guarantees an entry in the results list for every given legal select item. This “padding” ensures that when the Tcl clause is included, the results list can be parsed properly. If illegal select items are given, there are no corresponding entries in the results list. Commands that do not include the Tcl clause create output as before without this “padding.”

Because the Tcl list structure is already curly brace delimited, any given separator characters (specified with the dump or recordseparator clauses) are ignored when generating Tcl output. However, for readability, newlines are used as record separators between objects. For example, in an expand bus command that includes selects and the Tcl clause, all selected items for one object are included on one line, and a new line is started for each connected object. Newlines are considered simple white space by Tcl, and so cause no parsing problems.

To avoid issues with Tcl list operations, the three special characters ‘{’, ‘}’, and ‘\’ are escaped by the ‘\’ character wherever they occur in text appearing between curly braces.

This clause must follow the Dump clause, if used, and precede the Output clause. In temp queries, it must also follow any recordseparator clause used. For example:

print bus TYPE NAME REVISION [SELECT] [dump [RECORDSEP]] [tcl] [output FILENAME]; 
print set SETNAME [SELECT] [dump [RECORDSEP]] [tcl] [output FILENAME]; 
list ADMINTYPE NAME_PATTERN [SELECT] [dump [RECORDSEP]] [tcl] [output FILENAME]; 
expand bus TYPE NAME REVISION [SELECT] [dump RECORDSEP] [tcl] [output FILENAME]; 
expand set SETNAME [SELECT] [dump RECORDSEP] [tcl] [output FILENAME]; 
temp query TYPE_PATTERN NAME_PATTERN REV_PATTERN QUERY_EXP [SELECT] [dump [RECORDSEP]] [recordseparator SEPARATOR_STR] [tcl] [output FILENAME];

When expanding both business objects and sets and including the Dump clause, a RECORDSEP is required. However, when the Tcl clause is also included, the separator is ignored. For justification, see Example 11.

Output Format

The output from each Tcl select command is consistent with the expected MQL output, except that is uses Tcl list format. The results for each object are wrapped in a list, even when one object is returned, as is the case with the print command. Within each object record is a header section followed by a sequence of select result items, like this: 

{ object1-header-data    select-result-items } 
{ object2-header-data    select-result-items }
.
.
.

Header Data

The format of the header data depends on the actual command.

  • Print, List, and Temporary Query commands

    business object: {business object} {TYPE} {NAME} {REV}

    connection object: {connection} {ID} administration: {TYPE} {NAME}

    set: no set header. Each member uses: {member business object} {TYPE} {NAME} {REV}

  • Expand command
    {LEVEL} {REL_NAME} {FROM/TO} {TYPE} {NAME} {REV}

Select Results Data

Each item in the select-result-items is in the format:

{{select-item} results-list}

where each item in the results-list is:

{{name} {value}}

or the results-list is simply { } if an empty result.

Using the Dump Clause

When the Dump clause is specified, most of the header is dropped, the {select-item} is dropped, and just {value} is given for each item in the results-list.

Some commands (such as expand) require a RECORDSEP to be included after the dump keyword. When used with the Tcl clause, this character is still required, but it is ignored.

Output Examples

  1. A simple print business object with Tcl clause.
    MQL<2>print bus Assembly SA-300356 0 select id owner locker tcl;
    {business object} {Assembly} {SA-300356} {0} {{id} {{id} 
{20083.46775.20193.6352}}} {{owner} {{owner} {Joe Product-Manager}}} 
{{locker} {{locker} {bucknam}}}

    It might appear that there is some redundancy in the output in the select-result-items section. The first occurrence of an item (for example owner, above) matches the given select item and is followed by name/value pairs that resulted from the select item. Often the name field is redundant. However, when the select item results in many returned items (for example attribute.value or from.id) the name field gives added details. For more information, see Example 3.

  2. The same print bus command including the Dump clause:
    MQL<3>print bus Assembly SA-300356 0 select id owner locker dump tcl;	

{{20083.46775.20193.6352}} {{Joe Product-Manager}} {{smith}}
  3. A business object Print with a select that returns multiple items:
    MQL<4>print bus Assembly SA-300356 0 select from.id tcl;
    {business object} {Assembly} {SA-300356} {0} {{from.id}
 {{from[Documentation].id} {20083.46775.30402.24363}}
 {{from[Analysis].id} {20083.46775.30631.62767}} {{ from[Analysis].id}
 {20083.46775.30631.41948}} {{from[Plan].id} {20083.46775.30632.60059}}
 {{from[Required Tools].id} {20083.46775.30639.24886}} {{from[BOM-As Designed].id}
 {20083.46775.30663.9546}} {{from[BOM-As Designed].id} {20083.46775.6577.56182}}}
  4. The same print of multiple items with the Dump clause, eliminating headers:
    MQL<5>print bus Assembly SA-300356 0 select from.id dump tcl;
    {{20083.46775.30402.24363} {20083.46775.30631.62767} 
{20083.46775.30631.41948} {20083.46775.30632.60059} 
{20083.46775.30639.24886} {20083.46775.30663.9546} 
{20083.46775.6577.56182}}
  5. A temporary query with simple select in Tcl list output (with newline between object records):
    MQL<6>temp query bus Assembly SA* 0 limit 5 select id locker tcl;
    {businessobject} {Assembly} {SA-300.125} {0} {{id} {{id} 
{20083.46775.31292.44899}}} {{locker} {{locker} {}}} 
{businessobject} {Assembly} {SA-300127} {0} {{id} {{id} 
{20083.46775.20133.58276}}} {{locker} {{locker} {bucknam}}} 
{businessobject} {Assembly} {SA-300195} {0} {{id} {{id} 
{20083.46775.20117.54372}}} {{locker} {{locker} {bucknam}}} 
{businessobject} {Assembly} {SA-300315} {0} {{id} {{id} 
{20083.46775.20173.48444}}} {{locker} {{locker} {}}} 
{businessobject} {Assembly} {SA-300356} {0} {{id} {{id} 
{20083.46775.20193.6352}}} {{locker} {{locker} {bucknam}}}
  6. The same temp query with Dump clause:

    MQL<7>temp query bus Assembly SA* 0 limit 5 select id locker dump tcl;
    {Assembly} {SA-300.125} {0} {{20083.46775.31292.44899}} {{}} 
{Assembly} {SA-300127} {0} {{20083.46775.20133.58276}} {{bucknam}} 
{Assembly} {SA-300195} {0} {{20083.46775.20117.54372}} {{bucknam}} 
{Assembly} {SA-300315} {0} {{20083.46775.20173.48444}} {{}} 
{Assembly} {SA-300356} {0} {{20083.46775.20193.6352}} {{bucknam}}

  7. A temp query selecting attributes and their values:
    MQL<8>temp query bus * * * limit 1 select current revision attribute.value tcl;
    {businessobject} {NC Program} {GH02456} {A} {{current} {{current} {Planned}}}
{{revision} {{revision} {A}}} {{attribute.value} {{attribute[MachineType].value} 
{Machine Center}} {{attribute[Process Type].value} {Unknown}} {{attribute[Written By].value} 
{}} {{attribute[File Suffix].value} {.TAP}}}
  8. The same temp query with Dump clause:
    MQL<9>temp query bus * * * limit 1 select current revision attribute.value dump tcl;
    {NC Program} {GH02456} {A} {{Planned}} {{A}} {{Machine Center} {Unknown} {}{.TAP}}
  9. An expand set with newlines for each object:
    MQL<10>expand set "A1 - To Do" limit 5 select bus id tcl;
    {1} {Documentation} {to} {Drawing} {SA-300356} {A} {{id} {{id} 
{20083.46775.30402.28967}}}
    {1} {Analysis} {to} {Cost Analysis} {DA-3001356-1} {A} {{id} {{id} 
{20083.46775.65320.27011}}}
    {1} {Analysis} {to} {Design Analysis} {DA-3001356-1} {C} {{id} {{id} 
{20083.46775.26552.19182}}}
    {1} {Plan} {to} {Assembly Process Plan} {SA-300356} {0} {{id} {{id} 
{20083.46775.62627.22040}}}
    {1} {Required Tools} {to} {Setup Instructions} {SA-300356} {A} {{id} {{id} 
{20083.46775.17589.27146}}}
  10. The same expand set with Dump clause:
    MQL<11>expand set "A1 - To Do" limit 5 select bus id dump : tcl;
    {1} {Documentation} {to} {Drawing} {SA-300356} {A} {{20083.46775.30402.28967}}
    {1} {Analysis} {to} {Cost Analysis} {DA-3001356-1} {A} {{20083.46775.65320.27011}}
    {1} {Analysis} {to} {Design Analysis} {DA-3001356-1} {C} {{20083.46775.26552.19182}}
    {1} {Plan} {to} {Assembly Process Plan} {SA-300356} {0} {{20083.46775.62627.22040}}
    {1} {Required Tools} {to} {Setup Instructions} {SA-300356} {A} {{20083.46775.17589.27146}}
  11. An expand bus with Dump clause but no RECORDSEP:
    MQL<12>expand bus Vehicle M60000 0 from recurse to 1 select rel id dump tcl;
    1tclDOCUMENTATIONtcltotclManualtclM60001tcl0tcl974.54590.24670.436
    1tclDesigned Part QuantitytcltotclFront AxletclM66000tcl0tcl974.54590.42602.58431
  12. A typical Tcl program:
    set output [mql expand set "A1 - To Do" select bus id dump : tcl]
set count [llength $output]
foreach row $output {
  set level [lindex $row 0]
  set relation [lindex $row 1]
  set tofrom [lindex $row 2]
  set busobj [lrange $row 3 5]
  set busid [join [lindex $row 6]]
  puts “\[level: $level\] relationship\[$relation\] $tofrom $busid”
}

    With results similar to:

    [level: 1] relationship[Documentation] to 20083.46775.30402.28967
[level: 1] relationship[Analysis] to 20083.46775.65320.27011
[level: 1] relationship[Analysis] to 20083.46775.26552.19182
[level: 1] relationship[Plan] to 20083.46775.62627.22040
[level: 1] relationship[Required Tools] to 20083.46775.17589.27146
[level: 1] relationship[BOM-As Designed] to 20083.46775.30337.38798
[level: 1] relationship[BOM-As Designed] to 20083.46775.29481.42882
[level: 1] relationship[Product Spec to BOM] from 20083.46775.32142.28396
.
.
.