.Within/.Endwithin Statements--Enable/Disable Column Formatting Mode
The .within and .endwithin statements enable and disable column formatting mode in Report-Writer.
This statement has the following format:
.within | .wi columnname{, columnname} | all
other formatting statements
.endwithin | .endwi | .end within
The parameters for the .within and .endwithin statements are as follows:
columnname
The name of a column in the report within which other formatting statements are to be used. You can specify the column name as a delimited identifier by enclosing it in double quotes ("), if you have previously specified the .delimid statement.
all
Indicates that all columns in the report are to be used.
The columnname or all can be expressed as a variable. The comma (,) must be stated explicitly and cannot be part of columnname variable.
$columnvariable
Variable whose value is a column name or all. Precede the variable with a dollar sign ($).
Description
The .within and .endwithin statements switch Report-Writer into and out of column formatting mode. In column formatting mode, Report-Writer temporarily sets the margins of the report to the left and right margins for a given column, determined either by default (as described in Automatic Determination of Default Settings) or through the use of the .position, .width, and .format statements.
If you specify a variable as columnname, Report-Writer evaluates the variable during the loading of the report specification, before retrieving data.
Report-Writer processes all statements between the .within and the corresponding .endwithin statement using the margins for the specified column, rather than the margins for the report. If more than one column is specified or evaluated on the .within statement, or if the keyword all is used, Report-Writer applies the set of statements to each of the columns in turn.
When using the .within and .endwithin block of statements for a set of columns, you can invoke a slightly different set of formatting statements within each column, differing only in the column referenced by a formatting statement. To accomplish this, two special names are available for use in formatting statements while in column formatting mode. You can use them to refer to the column that is currently being used:
w_column
Can be used anywhere columnname would normally be used on a formatting statement, such as in .print w_column or .print sum(w_column).
w_name
Refers to the name of the column currently being used in the within block. You can use it to print out the actual column names.
When used in a .within block, these special names can also be values of variables where appropriate. For instance, the value of the variable colname is w_name in the following example:
.tab $colname
In another example, the value of the variable colval is w_column:
sum($col)
For examples of the use of these special names, see the examples in this section or the appendix “Report-Writer Report Examples.”
Because Report-Writer temporarily changes the margins of the report to the margins for a column while the .within statement is in effect, the positions referred to by the default values for the .left, .right, and .center statements are those of the column, rather than the full width of the report.
If the text you want to print spans more than one line per column in the .within section—that is, the text has more than one .newline command—then surround the .within section with the .block and .endblock statements. Report-Writer automatically executes a .top statement immediately before the .endwithin statement to simplify this type of specification.
Once you start to use the .within and .endwithin statements, you can find that the .position, .width, and .format statements take on additional usefulness.
Examples
1. Assume the following sequence of Report-Writer statements, where two of the column names are delimited identifiers:
.position "last name"(0), "first name"(16), address(32)
...
.within "last name", "first name", address
.pr w_name
.end within
Report-Writer prints the names of the three columns similar to this:
last name first name address
2. In the following example, the .within statements allow Report-Writer to print each column of the report in a similar format.
In the report header and footer section, a .block statement allows the centered titles and sums to use more than one line. In the detail section, only one line is used so a .block statement is not necessary. In the detail and the footer section for the report, the special name w_column is used.
Total
Population 18 to 65
11,113,976 9,600,381
5,193,669 4,820,324
8,875,083 7,833,474
10,652,017 9,646,997
712,567 698,802
694,409 663,043
19,953,134 17,761,032
[detail omitted]
‑---------- -----------
203,165,702 177,612,309
The following report example was used to create the two columns:
.name withinex
.query select tot_18to65 + tot_under18 + tot_over65
as totpot, tot_18to65
from pop
.header report
.position totpot (2,15), tot_18to65(20,15)
.format totpop, tot_18to65 ('zzz,nnn,nnn')
.block
.within totpop
.right .println 'Total'
.underline
.right .println 'Population'
.nounderline
.endwithin
.within tot_18to65
.newline
.underline
.right
.println '18 to 65'
.nounderline
.endwithin
.endblock
.detail
.within totpop, tot_18to65
.right . println w_column
.endwithin
.footer report
.block
.within totpop, tot_18to65
.right . println '-----------'
.right . print sum(w_column)
.endwithin
.endblock