Explanation Rule
Definition
A supplementary rule in an EH&S Expert rule set that specifies the type and level of detail of the explanation in table form of the rule-set pass results.
Structure
The EH&S Expert has been enhanced to include the required syntax elements to enable rule-set developers to formulate explanations for rule sets. To distinguish explanation rules from the other rules in a rule set, they are introduced with the keyword EXPLAIN. The explanation rules are run at the end of a rule-set run when all other rules have been processed and all interim and final results are available.
An explanation rule has the effect that rule-set data is output in the form of a table. The data records in the table result from the instances of the records and compositions used in the explanation rule. From these, nested subgroups can also result within the table if several records and compositions are output in an explanation rule.
With a number of explanation rules, several tables can be grouped together to form a full explanation. The tables are displayed in a tree structure.
Explanation rules also have a condition with which the selecting of data can be restricted.
You can use the following commands to construct explanation tables.
Function |
Meaning |
HEADLINE |
Headline for the table. The headline is one level higher in the display as a tree structure. This allows the table to be expanded and collapsed. |
HEADER |
Table header that is output once at the start of the table |
GROUPHEADER |
Header of a subgroup (record within a composition, ANY in a record or composition) |
LINE |
Table row |
GROUPFOOTER |
Footer of a subgroup |
FOOTER |
Table footer that is output once at the end of the table |
INDENT(n) |
Indentation of the table in a tree structure |
Note the following here:
Apart from INDENT the functions can have a variable number of parameters that fill the respective columns in the table. Text constants, fact names, expressions including all functions of the EH&S Expert, and special functions can be used as parameters.
If the explanation rule contains only facts without references to record or compositions, the table created comprises only one single row, plus the optional header and footer.
If the explanation rule contains facts for one single composition or record, one data row is output per instance if this is not restricted by conditions. The same applies if the explanation rule uses the ANY function on one single fact. GROUPHEADER and GROUPFOOTER are not relevant in this case.They appear once at the start and end of the table just like HEADER and FOOTER.
In HEADER and FOOTER, facts with references to compositions or records are not permitted.
If the explanation rule contains one of the following elements, the table maps a double or triple nested loop across the respective instances:
Facts for a record within a composition
Single ANY function on a fact with reference to one of the following:
A record
A composition
A record within a composition
Here you can use GROUPHEADER and GROUPFOOTER to give each of the inner loops a header and footer.
If the explanation rule contains facts for two different compositions, records, ANY functions, or any combinations, the table maps the cross product of the instances, which is usually restricted by a condition. Here it depends on which composition, record, or ANY function is named first in the explanation rule. The first named element determines the outer loop, and so on. Here you can use GROUPHEADER and GROUPFOOTER again; they must not, however reference the elements of their respective outer loop.
Data that is identical in consecutive data rows is not repeated.
You can also write a number of HEADER, FOOTER, GROUPHEADER, GROUPFOOTER, and LINE commands in succession to achieve multirow output.
When an explanation is displayed, the various elements of the explanation are at different levels in a tree structure:
Function |
Level |
|---|---|
HEADLINE |
1 |
HEADER |
2 with HEADLINE, 1 without HEADLINE |
GROUPHEADER |
2 with HEADLINE, 1 without HEADLINE (lower if nested) |
⇒ |
2 with HEADLINE, 1 without HEADLINE (GROUPHEADER + 1 level if nested in GROUPHEADER) |
GROUPFOOTER |
GROUPHEADER + 1 |
FOOTER |
2 with HEADLINE, 1 without HEADLINE |
With the INDENT command you can move all elements in the table to the right by one or more levels. You can also group a number of tables under one main node.
Example: Density Rule Set (DEMO2)
Below is an explanation of the demo rule set for calculating the density supplied with the EH&S Expert. The explanation appears in the form of a simple table without nesting. The enhancements to the current version without explanations are shown in boldface:
Note
It is only possible to display and process the EH&S Expert rule editor using the multiline mode.Choose
Tools
Options
and set the
Use Multiline Editbox
indicator on the
Edit
tab page.
FACTS
TmpDensity := 0,
Density(OUT),
COMPOSITION COMP
Percent(IN),
PercentUP(IN),
PercentLOW(IN),
Density(IN),
Ident(IN) // mapped to I:NAM,PROD, for example
END
RULES
RULE SUM_Density
If TRUE()
THEN
TmpDensity := TmpDensity + (comp.percent/100)*comp.density
END
RULE SET_Density
If TmpDensity > 0 THEN
Density := TmpDensity
END
// Calculate percentage part from upper and lower limit
// if average value is zero
RULE COMPUTE_PERCENTAGE_AVERAGE If Comp.Percent = 0
THEN
COMP.Percent := ( COMP.Percentlow + COMP.Percentup ) / 2
END
EXPLAIN Density
IF TRUE()
THEN
HEADLINE("Density Calculation")
HEADER("Component" , "Percent" , "Density" , "Weighted density"/right)
LINE (Comp.Ident , Comp.Percent, Comp.Density,
(Comp.Percent/100)*Comp.Density)
FOOTER("Average density", "" , "" , Density)
END
END
The explanation generated in this way then looks as follows:
Density Calculation
Component Percent Density Weighted density
sub1 50 10 5
sub2 20 20 4
sub3 30 30 9
Average density 18
Special Functions
The special functions listed below are available. They are marked with their own syntax in the stored user-defined text for the explanation so that they are expanded for display of the explanation in the logon language.
Function |
Meaning |
|---|---|
"[#<Phrase key>#]“ |
The syntax for internal phrase keys serves as a reference to a phrase in EH&S. This can be used for column headings but also for comments, such as background to laws. The value is taken from phrase mapping in the standard system. If no entry is found there, it is interpreted directly as an EH&S phrase key without warning. |
DESC( <fact name>) |
Reference to a fact name that must be mapped to an EH&S data element in mapping. The multilingual description of the data element from the ABAP dictionary is then displayed. |
PHRCODE( <fact name>) |
In the explanation, the phrase code is displayed instead of the phrase text if the fact contains phrase keys. |
The explanation rule for the sample rule set DEMO1 could thus appear as follows:
EXPLAIN
IF TRUE()
THEN
HEADER( DESC( FlashPoint), " ", DESC( RPhrase)),
LINE( FlashPoint, "->", RPhrase)
END
Phrases
Values with phrases assigned that are included in the explanation are also marked with their own syntax so that the internal phrase key is not displayed, but rather the phrase code and the phrase text in the logon language. The following criteria apply for identifying phrases:
The corresponding fact is subject to phrase mapping.
The internal phrase ID has the syntax [#...#].
The external phrase ID has a hyphen as the separator between the library and the key.
Temporary Facts
Temporary facts used in the rule set, which store interim results necessary for the explanation, should be included in mapping by the rule-set developer and mapped to an external ID in order to be able to derive the correct multilingual description from it and identify phrases.
Identification of Components
Rule sets often access data from components of a specification. To achieve a comprehensible explanation, you should identify components so they are easily recognizable. To do this, you should include additional IN facts in the rule set, which represent meaningful identifiers for the components.
Formatting
There are a number of options for formatting columns and rows. They are appended to the relevant column parameter or, for row formats, to the last column parameter.
Option |
Relates To |
Meaning |
|---|---|---|
/RIGHT |
Column |
Right-aligned display of column value |
/LEFT |
Column |
Left-aligned display of column value (default) |
/MID |
Column |
Centered display of column value |
/WIDTH=n |
Column |
Maximum column width (n = number of characters) |
/NL |
Row |
Insert additional blank row after row |
/NLBEFORE |
Row |
Insert additional blank row before row |
/LINE |
Row |
Insert line after row |
/LINEBEFORE |
Row |
Insert line before row |
Options that relate to columns are passed on by HEADER and GROUPHEADER to the data rows and footers below them.