7.18.1 DEF_BREAK Parameters
Specifies the name that is to be assigned to the group of report print lines defined by this command. The name specified must be unique within the function.
Specifies the field(s) that is to be printed on the report. An expandable group expression is allowed in this parameter.
Only RDML fileds are supported.
Specifies the condition that is to be used to "trigger" the printing of the break line(s) defined by this command. An expandable group expressions is allowed in this parameter.
*DEFAULT, which is the default value, indicates that the break line should only be triggered once, when the report is finished / closed by the ENDPRINT command or the termination of the function. This value is typically used to produce "grand" total break lines at the end of a report.
Otherwise, specify a list of field names that are to be used to trigger the printing of the break line(s). Every time any report line is printed LANSA compares the fields nominated in the list with their previous values. If any field nominated in the list has changed value the break line(s) will be produced.
Specifies the type of break line required.
*TRAILING, which is the default value, is typically used to produce break lines that trail after their associated detail lines.
*LEADING is typically used to produce break lines that are printed before their associated detail lines.
The difference between leading and trailing break lines is best illustrated by example. Consider the following detail (see DEF_LINE command) and trailing break line definitions:
DEF_LINE NAME(#DETAIL) FIELDS(#REGION #PRODES #VALUE)
DEF_BREAK NAME(#REGTOT) FIELDS(#REGVAL) TRIGGER_BY(#REGION)
A report produced using these line definitions might look like this:
|
In this example the line Region total 1400.00 is the trailing break line.
The use of the break lines as typical "trailing" subtotals can be seen. However, the appearance of the report can be improved by using a "leading" break line as well:
DEF_LINE NAME(#DETAIL) FIELDS(#PRODES #VALUE)
DEF_BREAK NAME(#REGTOT) FIELDS(#REGVAL) TRIGGER_BY(#REGION)
DEF_BREAK NAME(#REGNAM) FIELDS(#REGION) TRIGGER_BY(#REGION) TYPE(*LEADING)
When the report is produced now it would probably look something like this:
|
In this example the line Region NSW is the leading break line and the line Region total 1400.00 is the trailing break line.
Specifies the number of lines on the report that should be spaced before the break line(s) is printed. The default value is 2, but any value in the range 0 to 100 can be specified.
Specifies the number of lines on the report that should be spaced after the break line(s) is printed. The default value is 1, but any value in the range 0 to 100 can be specified.
Allows the specification of up to 50 "text strings" that are to appear on the screen panel or report. Each text string specified is restricted to a maximum length of 20 characters.
When a text string is specified it should be followed by a row/line number and a column/position number that indicates where it should appear on the screen panel or report.
For example:
TEXT(('ACME' 6 2)('ENGINEERING' 7 2))
specifies 2 text strings to appear at line 6, position 2 and line 7, position 2 respectively.
|
Portability Considerations |
In Visual LANSA this parameter should only be edited using the screen or report painter which will replace any text with a text map. DO NOT enter text using the command prompt or free format editor as it will not pass the full function checker if checked in to LANSA for i. |
All Platforms
The text map is used by the screen or report design facilities to store the details of all the text strings associated with the screen panel or report lines.
Once a screen or report layout has been "painted" and saved, all text details from the layout are stored in a "text map". The text map is then subsequently changed by using the "painter" again.
The presence of a text map is indicated by a TEXT parameter that looks like this example:
TEXT((*TMAPnnn 1 1))
where "nnn" is a unique number (within this function) that identifies the stored text map.
Some very important things about "text maps" and *TMAPnnn identifiers that you must know are:
- Never specify *TMAPnnn identifiers of your own or change *TMAPnnn identifiers to other values. Leave the assignment and management of *TMAPnnn identifiers to the screen and report design facilities.
- When copying a command that has an *TMAPnnn identifier, remove the *TMAPnnn references (ie: the whole TEXT parameter) from the copied command. If you fail to do this, then the full function checker will detect the duplicated use of *TMAPnnn identifiers, and issue a fatal error message before any loss occurs.
- Never remove an *TMAPnnn identifier from a command. If this is done then the associated text map may be deleted, or reused in another command, during a full function check or compilation. Loss of text details is likely to result.
- Never "comment out" a command that contains a valid *TMAPnnn identifier. This is just another variation of the preceding warning and it runs the same risks of loss or reuse of text.
- Never specify *TMAPnnn values in an Application Template. In the template context *TMAPnnn values have no meaning. Use the "text string" format in commands used in, and initially generated by, Application Templates.
Specifies the report with which this command should be associated. Up to 8 reports can be produced by a function at one time. Each report is identified by a number in the range 1 to 8. The default value for this report is report number 1.
Specifies the design/positioning method which should be used for fields that do not have specific positioning attributes associated with them.
*ACROSS, which is the default value for the DEF_BREAK command, indicates that fields should be designed "across" the report line (ie: one after another).
*DOWN indicates that the fields should be designed "down" the report page (ie: one under another).
Specifies the default identification method to be used for fields that do not have specific identification attributes associated with them.
*LABEL, which is the default value for the DEF_BREAK command, indicates that fields should be identified by their associated labels.
*COLHDG indicates that fields should be identified by their associated column headings.
*NOID indicates that no identification of the field is required. Only the field itself should be included into the report line(s).
Specifies the spacing between lines on the report that should be used when automatically designing a report. The value specified must be a number in the range 1 to 10. The default value for the DEF_BREAK command is 1.
Specifies the spacing between columns on the report that should be used when automatically designing a report. The value specified must be a number in the range 0 to 10. The default value for the DEF_BREAK command is 1.
Optionally specifies the name of a condition that indicates whether any column heading line(s) associated with fields in this break print line are to be printed in the header area of the report.
*NONE, which is the default value, indicates that no controlling condition applies, and any column headings associated with this break line should always be printed in the report header area, regardless of which line is actually being printed.
If a controlling condition is specified, it must be defined elsewhere in the RDML function by a DEF_COND (define condition) command. At the time that any print line is to be printed the status of the condition will be checked. Only when it is found to be true will the column headings associated with this break print line be included in the header area of the report.
Optionally specifies the name of a subroutine that is to be executed just prior to printing the break line.
*NONE, which is the default value, indicates that no subroutine should be executed before printing the break line.
If a subroutine name is specified, it must:
- Be defined within this function as a valid subroutine by using the SUBROUTINE command.
- Not have any parameters. Subroutines used this way cannot have parameters.
Any subroutine used with a break line should:
- Restrict itself to simple manipulations of fields that are to be printed on the break line. Fields other than those that appear on the print line may be changed but not in ways that are expected to communicate information to other parts of the RDML function at some later time.
- Avoid executing other subroutines.
- Avoid any screen panel interactions.
- Avoid printing any type of information at all.
These guidelines are not checked, but failure to observe them may lead to unpredictable results.
The logic used for invoking a TYPE(*LEADING) break line subroutine works like this:
<<if first usage or trigger values have changed>>
<<execute leading break subroutine>>
<<print the leading break line>>
<<endif>>
<<store current trigger values for next comparison>>
An example of using a subroutine with a TYPE(*LEADING) break line is as follows:
DEF_BREAK NAME(#REGION) FIELDS(#REG_CODE #REG_NAME) TRIGGER_BY(#REG_CODE) TYPE(*LEADING) SUBROUTINE(GET_REGION)
SUBROUTINE NAME(GET_REGION)
FETCH FIELDS(#REG_NAME) FROM_FILE(REGIONS) WITH_KEY(#REG_CODE)
ENDROUTINE
The leading break line is printed whenever a new region code is encountered. The break subroutine uses the current region code value to extract the associated region name from the regions table. This is an efficient approach because the subroutine is only executed when a change of region code occurs.
The logic used for invoking a TYPE(*TRAILING) break line subroutine is slightly more complex because the values printed on a trailing break line actually "trail behind" the apparent (and visible) values in the RDML function.
For instance, a trailing break line that is triggered by a change of region code, and also prints the region name, is set up so that the printed region codes and region names "trail behind" the current values of the region code and region name fields visible in the RDML function.
The reason for this is simple.
When the region code changes from "001" to "002", say, the trailing break line is triggered. If it printed the current value of the region code then it would show as "002" on the report.
So a special internal "trailing" field containing the "previous" value of region code is actually printed, which still contains the value "001".
This "trailing" logic is applied to all fields that are printed on TYPE(*TRAILING) break lines.
While this may appear complex, it actually makes the RDML level logic for the developer much simpler, because the complexity of "trailing" logic is catered for internally and need not concern the developer.
The trailing break print logic goes like this:
<<if this is not first usage and trigger values have changed>>
<<save current values of all fields used in function>>
<<restore all printed fields from their "trailing" values>>
<<execute trailing break subroutine>>
<<move all printed fields back into their "trailing" values>>
<<restore current values of all fields used in function>>
<<print the trailing break line (ie: the trailing values)>>
<<endif>>
<<store current trigger values for next comparison>>
At the completion of this logic all fields are restored back to what they were at the time that the logic was invoked.
This makes it effectively impossible for a trailing break line subroutine to "communicate" with other parts of the RDML function by changing field values.
An example of using a subroutine with a TYPE(*TRAILING) break line is as follows:
DEF_BREAK NAME(#REG_TOTAL) FIELDS(#REG_CODE #REG_NAME #REG_TOT1 #REG_TOT2 #REG_PCT) TRIGGER_BY(#REG_CODE) TYPE(*TRAILING) SUBROUTINE(REG_TOTAL)
SELECT FIELDS(#REG_CODE ... etc ...) FROM_FILE(SALES)
KEEP_TOTAL OF_FIELD(...) IN_FIELD(#REG_TOT1) BY_FIELD(#REG_CODE)
KEEP_TOTAL OF_FIELD(...) IN_FIELD(#REG_TOT2) BY_FIELD(#REG_CODE)
PRINT LINE(*BREAKS) <-
ENDSELECT <-
SUBROUTINE NAME(REG_TOTAL)
FETCH FIELDS(#REG_NAME) FROM_FILE(REGIONS) WITH_KEY(#REG_CODE)
CHANGE FIELD(#REG_PCT) TO('(#REG_TOT1 / #REG_TOT2) * 100')
ENDROUTINE <-
Like the preceding example the subroutine is only invoked when a region code changes. It extracts the region name from the region table and also sets #REG_PCT to be the percentage of totalled fields #REG_TOT1 and #REG_TOT2.
This routine will work well because it only uses and changes values that are actually printed on the break line.
This approach would be apparent if you ran this application in debug mode.
If you set up this application to stop in debug mode at:
- The PRINT LINE(*BREAKS) command
- The ENDSELECT command
- The ENDROUTINE command (of the REG_TOTAL subroutine)
Then assuming that the SALES file contained information for region codes "001" and "002", and that the SELECT loop had already processed all the region "001" information, and just read in the first region "002" record you would find:
At the PRINT command:
- Field #REG_CODE would contain "002".
- Field #REG_NAME would be blank.
- Field #REG_TOT1 would be the current total for region "002"
- Field #REG_TOT2 would be the current total for region "002"
- Field #REG_PCT would be zero.
At the ENDROUTINE command:
- Field #REG_CODE would contain "001".
- Field #REG_NAME would contain the name of region "001".
- Field #REG_TOT1 would be the final total for region "001"
- Field #REG_TOT2 would be the final total for region "001"
- Field #REG_PCT would be the region "001" percentage total.
At the ENDSELECT command:
- Field #REG_CODE would contain "002".
- Field #REG_NAME would be blank.
- Field #REG_TOT1 would be the current total for region "002"
- Field #REG_TOT2 would be the current total for region "002"
- Field #REG_PCT would be zero.