Overview

This training covers the SystemWeaver Path Query Language (SPaQL) functionality in the Item report generation features of swExplorer. Examples and exercises are provided.

Course Type

Suitable for class training or self-study.

Course Length

Approximately 1 to 2 day course.

Prerequisites

Exercises

The answers to all exercises can be found in the swExplorer ribbon tab Report Training>Answers under Path Query Language.


 

Note: This presentation does not cover GUI and view concepts.


Introduction

The SystemWeaver Path Query Language (SPaQL) is a comprehensive and compact language to query SystemWeaver data. It provides powerful logic and a means to operate on sets of data. It is constantly evolving and does not replace normal report traversing. The specialized context language for SystemWeaver can be used to generate information in reports and documents for complex scenarios that the basic report generation features cannot handle. It also provides a means of counting items and following parts backwards in the defined context. In addition, it enables you to "merge" different perspectives.


This course does not cover the complete functionality and available options. After completing this course, explore all available features by using the SystemWeaver Help accessed by clicking the ? in the swExplorer client or by taking additional courses.


Path Query Evaluation Editor

Path query expressions can be tested in the Path Query Evaluation editor. Normally, however, SPaQL is used together with other item report generation features. We will start by opening the Path Query Evaluation editor. To access it, click on the View drop-down and selecting Path query evaluation.



Expressions are entered into the ?> box at the top. Results are displayed in the area below it.


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: 



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



Note: As seen in the above example, the part order is NOT preserved. The main purpose of SPaQL is to collect and evaluate data. The standard means of traversing reports is still the best choice if part order is important. Using both constructs together produces the best results. 


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. 



Bildresultat för exercise icon freeExercise 1 - Printing Requirements

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture top node, use the Path Query Language to print all Requirements (RQ).
    Expected result:


Traversing Parts using Axis Steps

When traversing a structure, you may wish 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 Step
Description
part
Step forward, stopping on the part. Returns a set of the parts of an item.
back
Follow parts backwards. Returns a list of all items which include the current obj as the specified part.
defobj
From a part, step forward to the item. Returns the DefObj object of a part
issueref
From an item, follow an issue reference to the issue. Returns a list of all issues which reference the current obj


Axis steps are always inserted after the ”/” and before the SID it is operating on. The below two examples show how to traverse parts with Axis steps:





Bildresultat för exercise icon freeExercise 2 - Printing Requirements

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, use the Path Query Language to print all issues connected to the Application Components.
    Hint: The SID for issuereferenses = IR
    Expected result: 


SPaQL - Single Items and Sets

SPaQL 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:



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 the Help manual.



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: 



Bildresultat för exercise icon freeExercise 3 - Printing Requirement Verification Attribute

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. Select Requirement 1 in the structure tree.
  4. Get the Verification Method attribute (SID=ABVM) for Requirement 1 using SPaQL.


Bildresultat för exercise icon freeExercise 4 - Printing Requirement Priority Attribute

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, use the Path Query Language to get all Requirements and print the Prio attribute(SID=PRIO)

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. The the below example, the first three requirements have a Prio value of 1. 



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



The [ ] Operator

The ”[]” operator is used to filter SPaQL 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.



Example 2

Returns all application components that have more than one requirement.



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.


Operator
Description
*
Multiply
+,  -
Plus, Minus
>, <
Greater Than, Less Than
=, !=
Equal, Not Equal
in

[]
Predicate
|
Set union
all ... satisfy ... any ... satisfies ...
Set expressions
not
Conditional not
and
Conditional and
or
or
if .. then .. else
Conditional
:=
Assignment

Bildresultat för exercise icon freeExercise 5 - Printing Components with Particular Attribute Value

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, select all application components that have at least one requirement where the Prio attribute equals 3.
    Expected result:

Set Operations

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

  • Minus
  • Union
  • In


Minus


Union



In



Bildresultat för exercise icon freeExercise 6 - Check Send Ports using "in"

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, check if all send ports have at least one corresponding receive port using the ”in” operation.


Bildresultat för exercise icon freeExercise 7 - Check Receive Ports using "minus"

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, find all receive ports that do not have a corresponding send port using the ”minus” operation.
    Expected result: 


Bildresultat för exercise icon freeExercise 8 - Printing End to End Functions

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, present all End to end functions available, both in the application components and in the End to End Function List.
    Expected result: 


Using SPaQL in Reports, Grids, etc. 

You can apply your newly gained SPaQL knowledge in the Report Editor. There may be cases where you would like to see more information than is available in the standard views in swExplorer or in the available report tags. The solution is to use so called field codes which support viewing of additional information like properties or attributes. It is possible to use SPaQL in the tags used for field codes.


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



Tip: SPaQL expressions can be used in every place where #{} is valid.

 


Bildresultat för exercise icon freeExercise 9 - Path Expression in Text Tag

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, try out some of your earlier exercise solutions inside the Text tag.

SPaQL 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 ' '. 



+ NewLine

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



Special XML Tags for Using SPaQL in Configurable Views

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

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


<ForEach>

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


<ForEach select="path-expression"/>


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.



Note: Sorting is supported by using order methods in the path expression. If no order method is used a path expression returns a set, which by default is traversed in alphabetic (ascending) order.


<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. 



<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.



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.



Bildresultat för exercise icon freeExercise 10 - Printing Requirement Names with Defined Prefix

  1. Open Item x0400000000000292.
  2. Open the Reports editor.
  3. From the Vehicle Architecture, print all requirements that have Prio =1 with the text ”High! - ” before the requirement name and all other requirements with ”Low! -” before the name.
  4. Try to solve it with both <If> and <When>.
    Expected result: 


SPaQL Variables

Results in SPaQL can be assigned to variables in the context of a report. In other words, a variable tag is a means of accessing values from SPaQL. 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.


Note: The value of a variable can only be assigned once. This means that a variable, as identified by its name, may only occur in a single <Variable> element and there is no way to change the value again. However, for elements that will be evaluated for multiple parts of the model structure (like ForEachPart), the assigned value of a variable may differ for each model element.


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



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.


Bildresultat för exercise icon freeExercise 11 - Create a Variable That Contains All of the End To End Functions

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, create a variable with the name ”endToEndFunctions” that contains all the End To End Functions found in the End To End Function List.
  4. Print the End To End Functions one per row.
    Expected result: 


Bildresultat för exercise icon freeExercise 12 - Combining New and Old Knowledge

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, print only the application components that realize an End To End Function available in the End to End Function List. The order of the application components shall correspond to the structure tree.
    Expected result: 


What's Next?

We hope that you are pleased with this course and have increased your knowledge of the SystemWeaver Path Query Language. You can extend your skills by practicing the numerous scripting options described in the Path Query Reference section of the Help.