Using Explorer relationship reports to create Explorer diagram
The Explorer Relationship Report should yield a set of "paths" between pairs of objects, which will be represented on the diagram as line symbols. Dragging it out of the Explorer and dropping it onto the diagram will run the report.
The top level of the report defines the first objects of the pairs. Given that the purpose of the report is to relate pairs of objects already represented on the diagram, System Architect parameterizes the top level by qualifying it with the Identities of some or all of the items currently represented on the diagram. The second objects of the pairs are identified with a Select statement selecting Identity with the legend "SATargetID". This statement will usually (but need not necessarily) be at the last level of the report. When it is intended as the last level of the report, it can be omitted from the report's content, since System Architect will detect its absence and append it to the last level of the report.
Since:
•the levels of the report defining the first and second objects of the pairs must be object levels rather than relationship levels and
•the reporting system requires that the top level must always be an object level and
•the first and second objects of the pairs must come from different levels of the report, then
The report must contain an even (but non-zero) number of Join statements between the top level and the level carrying the SATargetID identifier.
You can use the Report Generator to create a report and select the criteria you want to report on. This information can be copied and pasted into the Explorer Reports Content property. You can also use Edit Content in the definition report to create a report.
Creating an Explorer relationship report
1 Select Dictionary > New Definition or select Definitions in the All Methods tab in the Explorer, right‑click it, and then click New.
The Select new type for All Methods dialog appears.
2 Double‑click Explorer Relationship Report.
The New Definition dialog appears.
3 Enter a name, and then click OK.
4 In the Description property, supply a brief description of the purpose of the report.
5 In Content, supply the reports specifications. Edit Content supplies the reporting interface and enable you to create the report. For pre-existing reports the Text Editor will be provided to you to create or change the report information.
6 On page 2 of the Introduction tab you can also specify Colors for the Pen and Font. This allows you to make the relationships created by different reports easily distinguishable.
Example R1
Join
Where relation = "contains"
Join
Select Identity Legend "SATargetID"
Join
Select Relation
Where relation = "defined by"
Notice that this example lacks much that one would have expected in a report. The top level is empty, but System Architect will add material here. There are no Select clauses, but this need not be so. There are no OrderBy clauses. They offer no functional advantage for these reports and would only slow down the reporting system.
System Architect, before running the report, appends material in front and behind to complete the report as System Architect needs it. Example R1 shown above effectively becomes:
Example R1a
TABULAR 1
{ Select Identity Where Identity = #DDIDS#
Join
Where relation = "contains"
Join
Select Identity Legend SATargeted
Join
Select Relation
Where relation = "defined by"
}
System Architect also provides a value for the parameter #DDIDS# when the report is run. This value is a list of the Identities of some or all the objects currently represented on the diagram and the list depends on where the report is dropped.
•If the drop point is in empty space on the diagram, the Identities of all the objects represented on the diagram are used.
•If the drop point is inside a Collection (but not on a node symbol inside that Collection), the Identities of the objects inside the Collection only are used.
•If the drop point is on any other node symbol, the Identity of the object represented by that one symbol is used.
In response to running a Relationship Report, System Architect will add to the diagram a Relationship line between the symbols representing the two items of each pair. If a pair is yielded by the report for which either of the pair is not represented on the diagram, System Architect ignores the pair.
When the report Example R1 is run, System Architect finds those pairs for which:
•the first of the pair is represented somewhere on the diagram and
•has the relationship "contains" with
•some unspecified object which is the second of the pair
•provided it enjoys the relationship "defined by".
That is - provided that the encyclopedia has abused neither the "contains" nor the "defined by" relationships: it shows which symbols with definitions are on which diagrams: where those symbol and diagrams are currently represented on the Explorer Diagram. A report specification that is safer against relationship abuse would be more specific, like this:
Example R2
Where Class = Diagram
Join
Where relation = "contains"
Join
Where Class = Symbol
Select "Identity" legend "SATargetID"
Join
Select Relation
Where relation = "defined by"
Join
Where Class = Definition
To demonstrate the use of "SATargetID", if example R2 is changed slightly so that this clause is at the last level of the report, thus:
Example R3
Where Class = Diagram
Join
Where relation = "contains"
Join
Where Class = Symbol
Join
Select Relation
Where relation = "defined by"
Join
Where Class = Definition
Select "Identity" legend "SATargetID"
System Architect draws relationship lines between diagrams represented on the diagram and definitions represented on the diagram: where those definitions actually define one or more symbols. If the last line was omitted, System Architect appends it for the user.
In summary:
The first objects of the pairs depends on the drop point:
•If the report is dropped into empty space on the diagram, System Architect restricts the first objects in the pairs to those currently represented anywhere on the diagram.
•If the report is dropped into a Collection, System Architect restricts the first objects in the pairs to those currently represented in the Collection.
•If the report is dropped onto a Node symbol, System Architect restricts the first objects in the pairs to that currently represented by that node symbol.
The second objects of the pairs are restricted by the report’s content, and are identified by the "SATargetID" legend.
•If the report includes the "SATargetID" legend, the report level for the second objects of the pairs are therefore specified by the user.
Additionally, the report level for the second objects of the pairs is assumed to be the last.
As with the Explorer object report, before a relationship report is actually run, it is scanned to ensure that there are no parameters whose values you should supply. If there are, you are prompted for them and then the report is run. Therefore, this report:
Example R4
Asks you for the symbol type value before the report is run.
Where Class = Diagram
Join
Where relation = "contains"
Join
Where Class = Symbol
Where Type = #TYPE#
Join
Select Relation
Where relation = "defined by"
Join
Where Class = Definition
Note If the symbol type has an embedded space, such as "Data Object", put the value in the quotes. To see the name of the relation on the line in the Explorer diagram, add a "Select Relation" statement to the report, as seen in the examples above.