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.