The SystemWeaver Path Query Language is a comprehensive and compact language to query SystemWeaver data. It provides a way to navigate the item/part structure and to select lists of items and calculate values from the data. This specialized language for SystemWeaver can be used to generate information for complex scenarios that the basic Script Language features cannot handle. It also provides a means of counting items and following parts backwards in a defined context. In addition, it enables you to "merge" different perspectives. This article introduces the SystemWeaver Path Query Language functionality.

• Path Query Evaluation Editor
• Traversing Parts
• Traversing Parts using Axis Steps
• Single Items and Sets
• Attributes and Object Properties - Single Item
• SystemWeaver Object Properties
• Attributes and Object Properties - Sets
• More on Methods
• The [ ] Operator
• Basic Operators
• Set Operations
• Using Path Query Language in Reports, Grids, etc. 
• Flexibility in Formatting Results
• Special XML Tags for Using Path Query Language in Configurable Views
• Path Query Language Variables

Prerequisites

• Familiar with the SystemWeaver meta model building blocks (e.g., Items, Parts and Attributes)
• Familiar with the SystemWeaver Explorer Interface and common operations
• An installation of the SystemWeaver Explorer client (swExplorer)
• Knowledge of XML (A good resource is w3schools' XML tutorials)
• Assignment of the SW Architect role in the server
• An installation of the SystemWeaver Architect client (swArchitect)
• Familiar with SystemWeaver Script Language

Path Query Evaluation Editor

Path query expressions can be tested in the Path Query Evaluation editor. Normally, however, the Path Query Language is used together with other item report generation features, but it's a useful tool. 

Traversing Parts

Parts are traversed by starting with a forward slash ”/” and then entering the Part SID. The expression shown below will return all of the Application Components : 

Example

/XESX/EXAC

If you enter the above expression into the Path Query Evaluation editor and press Enter, the result will be: 

You can evaluate multiple path queries in the editor one after another and each result will appear in the results area in the order in which you evaluate. The result area is editable.

Traversing Parts using Axis Steps

When traversing a structure, you may want to move to a part, or traverse backwards, etc. This is done using axis steps. Some of the available axis steps and their functions are explained below. For a complete list of axis steps, consult the Help. 

Axis steps are always inserted after the ”/”, followed by two semi-colons (::) and before the SID it is operating on as shown below. The two examples illustrate how to traverse parts with "back" and "part" axis steps:

Example

/back::3E2F

/XESX/part::EXAC

Single Items and Sets

The Path Query Language works with sets when handling more than one Item. A set is an unordered collection of unique Items. A set is indicated by  ”[” and ”]” surrounding the result as shown below. When creating reports, grids, etc., it is important to know if you are operating on sets or single items because accessing attributes and object properties are done in different ways.

Attributes and Object Properties - Single Item

Attributes are accessed by writing ”@ASID” for single items. Object Properties are accessed by writing ”PropertyName” for single items. 

Examples

Accessing an Attribute

Accessing an Object Property

SystemWeaver Object Properties

SystemWeaver object properties are used to access information about an item. Below is a list of all of the available object properties. 

For more information on output type and which objects they are valid for, see SystemWeaver object properties in the application Help:

Attributes and Object Properties - Sets

When accessing object properties for items in sets, the method ”Select(”attributeOrProperty”)” is used. This will return a new list containing the result of the ”Select” function for every individual item in the list.

Examples 

Accessing an Attribute

Accessing an Object Property

More on Methods

Unlike the path expressions, methods used on sets return lists. Lists derived from methods do not require occurrences to be unique. This is useful when the information queried for in a method contains multiple values that are the same. In the below example, the first three requirements have a Prio value of 1. 

<Report>
  <Text>#{?/XESX/EXAC/IBAR.Select(@PRIO)}</Text>
</Report> 

Below is a list of some of the available methods. For more information and to view a complete list, see the Help manual.

Count

• Returns the number of objects in a set
• Example: /XESX.Count

Max

• Returns the highest numerical value in the list
• Example: /SID.Select(@ASID).Max

Distinct

• Returns a list with unique occurrences of items or values. Only useful on lists
• Example: /SID.Select(@ASID).Distinct

Matches

• Performs a regular expression check. Returns true or falue whether a match was found or not
• Example: /SID.Select(Name).Matches("hdlr")

Sum

• Returns the mathematical sum of all values in a list
• Example: /SID.Select(@ASID).Sum

The [ ] Operator

The ”[]” operator is used to filter the Path Query Language queries based on a defined logical expression. Below are a couple of examples. 

Example 1

Return all requirements found below the application components whose Priority attribute (SID=PRIO) equals 1.

/XESX/EXAC/IBAR[@PRIO=1]

Example 2

Returns all application components that have more than one requirement.

/XESX/EXAC[/IBAR.Count>1]

Basic Operators

Below is a list of all of the available basic operators, in order of precedence from highest to lowest, and a short explanation. More than one operator is allowed in a ”[]” expression.

Set Operations

When comparing sets, the following operations prove to be useful: 

• Minus
• Union
• In

Minus

set1 - set2

• Removes all occurrences in one set from another. The least possible value is an empty set. 
• Examples: [1,2,3] - [2,3] = [1],   [2,3] - [1,2,3] = []

Union

set1 union set2

• Adds two sets together
• Example: [1,2,3] union [2,3,4] = [1,2,3,4]

In

set1 in set2

• Returns true if all members of set1 are included in set2
• Examples: [1,2,3] in [2,3] = false,  [2,3] in [1,2,3] = true,  [] in [1,2,3] = true

Using Path Query Language in Reports, Grids, etc. 

There may be cases where you would like to see more information than is available in the standard views or in the available view tags. The solution is to use field codes which support viewing of additional information like Properties or Attributes. It's possible to use the Path Query Language in the tags used for field codes.

For example, in a report configuration you can use it in any <Text> element. Enclose the field code with a hash sign # and curly brackets { } and start it with a "?":

Flexibility in Formatting Results

Join

When printing, sets are presented by default inside the ”[ ]” brackets. Sometimes, another presentation format is preferred. This can be achieved with the ”Join” operation. The ”Join” operation creates a string of the items in the set, delimited by what has been defined inside the ' '. 

Example

<Report>
    <Text>#{?/XESX/EXAC.Join(', ')}</Text>
</Report> 

+ NewLine

The special keyword ”NewLine” inserts a newline character. Note that the ”+” is required when combining the string with the ”NewLine” keyword.

Example

<Report>
    <Text>#{?/XESX/EXAC.Join(', ' + NewLine)}</Text>
</Report> 

Special XML Tags for Using Path Query Language in Configurable Views

There are some special XML tags for using path queries in reports, grids and other configurable views. They are: 

• <ForEach>
• <If>
• <Choose>

<ForEach>

ForEach is the path query version of <ForEachPart>, but the expressions here can be much more complex. 

The tags following the ForEach are applied to all items that fulfill the path expression. 

The below example produces a similar result as the <Text> tag demonstrated earlier. However, here ForEach is used to loop through the resulting set produced by /XESX/EXAC.

Example

<Report>
    <ForEach select="/XESX/EXAC">
        <Text>#{Name}</Text>
    </ForEach>
</Report> 

<If>

The content of an <If> tag only executes if the condition set up in the ”test” is true. In the below example, only application components that have more than one Receive Port will be included in the results. 

Example

<Report>
    <ForEach select="/XESX/EXAC">       
        <If test="/ITIS.Count>1">
            <Text>#{Name}</Text> 
        </If>
    </ForEach>
</Report> 

<Choose>

<Choose> is a more advanced version of <If>. If the condition in a <When> statement is met, its content will be executed. If the condition is false, the next <When> statement will be tested. If all <When> statements are false, the content of the <Otherwise> tag will be executed.

Example

<Report>
  <ForEach select="/XESX/EXAC">       
    <Choose>
      <When test="/ITIS.Count=1">
        <Text>One port: #{Name}</Text>   
      </When>      
      <When test="/ITIS.Count=0">
        <Text>Zero port: #{Name}</Text>   
      </When>       
      <Otherwise>
        <Text>More than one port: #{Name}</Text>      
      </Otherwise>      
    </Choose>
  </ForEach>
</Report>

Sets and Boolean Expressions

It is possible to use a resulting set to evaluate a condition using <If>, <When>, etc. If the set is empty, the expression will be evaluated to false. If the set contains at least one element, it will evaluate to true. In the below example, only application components that have at least one Receive Port will be printed.

Example

<Report>
    <ForEach select="/XESX/EXAC">       
        <If test="/ITIS">
            <Text>#{Name}</Text> 
        </If> 
    </ForEach>
</Report>

Path Query Language Variables

Results in path queries can be assigned to variables in the context of a report. In other words, a variable tag is a means of accessing values from the path queries. They are valuable when complex expressions are evaluated in succession and intermediate results are needed for subsequent evaluation and use. They can also be used to avoid repeating the same path expression twice or more. 

<Variable name="" as="" select="path-expression">

name: defines the name of the variable to be used in path expressions.
as: specifies the type of the variable. The types that are supported by the Path expressions are defined in the Path Query Reference manual in the Help.

select: specifies the path expression to be used when the value is assigned to the variable.

The example below shows how to assign a value to a variable and then accessing it in the <Text> tag.

<Report>
    <Variable name="applicationComponents" as="[Item]" select="/XESX/EXAC"/>       
    <Text>#{?$applicationComponents}</Text> 
</Report> 

The "?" question mark tells that a path expression should be evaluated and the "$" dollar sign tells that the value of the variable should be used.

What's Next?

Learn about using the Path Query Language with creating charts in Combining Knowledge - Charts and the Path Query Language, or how to define custom functions using path expressions.