Expand Set Command

Syntax

When using the Expand Businessobject command, you are working with a single business object. To expand multiple objects, use the Expand Set command, which expands each of the objects contained within a set. The Expand Set command also lets you search for relationships that meet the search criteria.

expand set NAME [user USER_NAME] [EXPAND_ITEM{EXPAND_ITEM}];

• NAME is the full specification of a set name. Since MQL will use the names of the objects from the set, you do not need to specify an object with this command. MQL will expand each set depending on the keyword (and values) that you specify.
• EXPAND_ITEM is one of:

  from

  to

  type PATTERN {,PATTERN}

  relationship PATTERN {,PATTERN}

  fixed points ID [,Id]

  withroots

  filter PATTERN

  activefilters

  reversefilters

  view NAME

  recurse [to | N |]

  recurse to |all|

  [into|onto] set NAME

  SELECT_BO

  where WHERE_CLAUSE

  SELECT_REL

  DUMP

In addition to a list of business objects that meet the specified criteria, the Expand Set command provides information about the connections. The level number of the expansion and the relationship type of the connection are provided along with the business object name, type, and revision.

You can also use the Recurse argument to indicate that you want to expand the business objects connected/related to the initially specified business object.

For more information, see Evaluate Query.

Relationship Expressions

Select expressions are applied directly to relationship instances, enabling selection of its relationship attribute values for use in Indented Tables and Visual Cues.

For example, the following can be used in a table column definition:

relationship [Drawing].attribute[Quantity] = 

Expanding From

When you use the From form of the Expand Set command, you expand away from the starting object. This gives you all the related objects that are defined as the TO ends in a relationship. Consider the starting object as the tail of the arrow and you are looking for all the arrow heads. The From form uses the syntax:

expand set NAME from [relationship PATTERN] [type PATTERN] [RECURSE_CLAUSE]
   [SET_CLAUSE|DUMP CLAUSE]];

The From form of the Expand clause returns all objects connected from the starting object (the arrow points out) regardless of the relationship used.

• NAME is the full specification of a set name.
• PATTERN is the pattern of the relationship or type name.
• RECURSE_CLAUSE expands the business object from which the initially specified business object is connected (for more information, see Recurse Clause).
• SET_CLAUSE places the output of the expand command into a set. All forms of the Expand Set command use a Set clause (for more information, see Set Clause).
• DUMP_CLAUSE specifies a general output format for the expanded information (for more information, see Dump and Output Clauses).

For example, assume you have a set of components which are used in larger assemblies. You need a list of all objects that each part goes into. The command would be:

expand set Components from;

This might produce a list of objects such as a calculator, telephone, VCR, and so on. Since no other criteria is specified, the From form of the Expand Set command gives you all objects that occupy the to end of a relationship definition.

Expanding To

When the To form of the Expand Set command is used, the set’s business objects are again used as the starting point. However, now it is assumed that each object is defined as the TO end of the relationship definition. Therefore, you are looking for all objects that lead to the named object. These are the objects defined as the FROM ends in a relationship definition.

The To form of the Expand Set command uses the syntax:

expand set NAME to [relationship PATTERN] [type PATTERN] [RECURSE_CLAUSE] [SET_CLAUSE|DUMP CLAUSE];

The To form of the Expand clause returns all objects connected to the starting object (the arrow points in) regardless of the relationship used.

For a description of the clauses, see Expanding From.

Using the To form is useful when you want to work backwards. For example, you mighs want to know what components make up each assembly in a defined set. For example:

expand set "Assembly Components" to;

This might give you objects that contain buttons, plastic housings, printed circuit boards, and so on. All related objects defined as the FROM connection end are listed.

Relationship Clause

This clause displays all objects connected in a specific relationship. This is useful when you are working with an object that could use multiple relationship types. If the starting object can only connect with one relationship, this form has the effect of listing all the connection ends used by the starting object. These ends can be defined as a TO end or a FROM end—it does not matter. Only the relationship type is of importance.

The Relationship clause uses the syntax:

expand set NAME [from|to] [relationship PATTERN] [type PATTERN] [RECURSE_CLAUSE] [SET_CLAUSE|DUMP CLAUSE];

The Relationship clause of the Expand Set command returns all objects connected to the starting object with a specific relationship. The command can be made more particular by specifying the direction of the relationship and/or the types of objects to return.

For a description of the clauses, see Expanding From.

For example, assume you have a set of drawing objects. These drawings could use a number of relationships such as a User Manual Relationship, Design Relationship, Marketing Relationship, Drawing Storage Relationship, and so on. You might want to examine all objects that use a particular type of relationship. For example, you might want a list of all objects that have used each drawing in some marketing way. To do this, you might enter a command similar to:

expand set "Drawing Collection" relationship "Marketing Relationship";

This command expands each object contained within the set named “Drawing Collection.” As each object is expanded, MQL lists any related objects that have the Marketing Relationship type. It searches through all the object connections for the Marketing Relationship type. If MQL finds a relationship with the type that uses the object being expanded, the other connection end is displayed and the end’s directional relationship is identified. It does not matter whether the related objects are defined as the FROM end or the TO end of the relationship. Only the relationship type is of importance.

Type Clause

This clause displays all related objects of a specific object type. This is useful when you are working with a set of objects that could be connected to multiple object types. If the starting object can only connect with one object type, this form is similar to the Relationship form using a wildcard pattern. The Type form uses the syntax:

expand set NAME [from|to] [relationship PATTERN] [type PATTERN] [RECURSE_CLAUSE] [SET_CLAUSE|DUMP CLAUSE];

For a description of the clauses, see Expanding From.

For example, assume you have a set that contains training course objects. To each object, you might have related objects that are of type Evaluation, Student, Materials, Locations, and so on. You might want to examine all Evaluation type objects to trace a course’s progress in meeting student needs. To do so, enter a command similar to:

expand set “Training Courses” type Evaluation;

This command expands each of the objects contained in the “Training Courses” set. It lists any related objects that have the Evaluation type. Those objects might belong to multiple relationship types (such as “Professional Evaluation Relationship” or “Student Evaluation Relationship”). It does not matter if the related objects are defined as the FROM end or the TO end of the relationship. Only the object type matters in the location and display of the output objects.

Withroots Keyword

You can include the root object by including the withroots keyword with all selectables to make it easier for client apps to identify a hierarchy.

MQL<9>expand set set_1 recurse to 2;
1 r2 to t2 t2-2 0 
2 r2 to t2 t2-3 0 
2 r3 to t2 t2-2-2 0 
2 r3 to t2 t2-2-3 0 
2 r1 from d12 d12-2 0 
2 r1 from d11 d11-3 0 

MQL<10>expand set set_1 recurse to 2 withroots; 
0 t2 t2-1 0 
1 r2 to t2 t2-2 0 
2 r2 to t2 t2-3 0 
2 r3 to t2 t2-2-2 0 
2 r3 to t2 t2-2-3 0 
2 r1 from d12 d12-2 0 
2 r1 from d11 d11-3 0 
2 r2 from t2 t2-1 0

MQL<19>expand set set_1 recurse to 2 select bus id dump; 
1 r2 to t2 t2-2 0 
20768.23721.38088.36415 

2 r2 to t2 t2-3 0 
20768.23721.38088.39031 

2 r3 to t2 t2-2-2 0 
13576.55552.30896.29472 

2 r3 to t2 t2-2-3 0 
6384.39445.50345.7641 

2 r1 from d12 d12-2 0 
20768.23721.38088.32444 

2 r1 from d11 d11-3 0 
20768.23721.38088.24862

 MQL<20>expand set set_1 recurse to
 2 withroots select bus id dump; 
0 t2 t2-1 0 
20768.23721.38088.35693 

1 r2 to t2 t2-2 0 
20768.23721.38088.36415 

2 r2 to t2 t2-3 0 
20768.23721.38088.39031 

2 r3 to t2 t2-2-2 0 
13576.55552.30896.29472 

2 r3 to t2 t2-2-3 0 
6384.39445.50345.7641 

2 r1 from d12 d12-2 0 
20768.23721.38088.32444 

2 r1 from d11 d11-3 0 
20768.23721.38088.24862 

Filter and Activefilter Clauses

This clause allows you to specify an existing filter(s) that is defined within your context to be used for the expansion. You can use wildcard characters or an exact name. For example:

expand set Assembly 12345 1 filter OpenRecs;

In addition, you can use the activefilter clause to indicate that you want to use all filters that are enabled in within your context. For example:

expand set Assembly 12345 1 activefilter;

Recurse Clause

Once you have a list of related objects, you can expand these objects. The Recurse clause of the Expand Businessobject command expands through multiple levels of hierarchy by applying the Expand command to each business object found:

recurse to [N|all]

• N is any number indicating the number of levels that you want to expand.
• all indicates that you want to expand all levels until all related business objects are found.

Set Clause

Once you have a list of related objects, what do you do with them? In some cases, you can simply search for a particular object and you will not need to reference the output object again. In that case, you might want to display the expansion output on your terminal. However, in other cases, you might want to capture the output and save it. That is the reason for the Set clause of the Expand Set command.

The Set clause uses the following syntax:

into|onto set SET_NAME

• SET_NAME is a valid name value that will be assigned to the set.

When the Set clause is included within the Expand Set command, the related objects are placed within a set and assigned a set name. This set might already contain values or it might be a new set created for the purpose of storing this output.

When it is an existing set, the previous values are either replaced or added onto depending on the keyword you use to begin the Set clause:

The Set clause is optional. If no Set clause is included with the Expand Set command, the output listing of related objects is displayed.

Dump and Output Clauses

You can specify a general output format for listing the expanded information to a file and for output. This is done with the Dump clause:

[dump “SEPARATOR_STR”] [output FILENAME]

• SEPARATOR_STR is a character or character string that should appear between the field values. It can be a tab, comma, semicolon, carriage return, and so on. If you do not specify a separator string value, a space is used.
• FILENAME identifies a file where the print output is to be stored.

The Dump clause specifies that you do not want to print the leading field name (a space) and that you want to separate the field names with the separator string you provide.

Separator strings can make the output more readable. If many of the business object have similar field values, using tabs as separators will make the values appear in columns.

The Output clause prints the expanded information to a file that you specify (FILENAME).

Terse Clause

You can specify the terse clause so that object IDs are returned instead of type, name, and revision. This is done with the Terse clause. For example, the following command returns a list of object IDs for objects connected to the specified Part:

expand set Part "35735" A terse;

Limit Clause

Since you might be accessing very large databases, you should consider limiting the number of objects to display. Use the Limit clause to define a value for the maximum number of objects to include in the expansion. For example, to limit the expansion to 25 objects, you could use a command similar to the following:

expand set Part "35735" A limit 25;