The topics in this section provide information on reporting through the Zim programming environment.
Refer to the following sections for more information:
Category: Reports
Report Item Format Options
Any meaningful combination of the following options can be applied to any value displayed in a report:
| CENTER | The Report Generator is to center the associated item on the current line. Centering is relative to the PAGEWIDTH specified in the REPORT FROM command. The default value for PAGEWIDTH is 80. |
| COLUMN n | The Report Generator is to start display of the associated item at character column n. COLUMN cannot be used in conjunction with SPACES. COLUMN 1 is automatic for the first item in each heading or detail line command. |
| HEADING ‘text’ | The Report Generator is to use text as the heading for the associated item. (Normally, the heading depends on the source of the item: field names for fields from EntitySets and so on; object names, for variables and constants; spaces, in all other cases.) To turn headings off, specify COLUMN HEADING OFF in the DETAIL LINE command. |
| LINE n | Before displaying the associated item, the Report Generator is to skip to line n on the current page. The value of n must be greater than the current line number. LINE cannot be used in conjunction with NEWLINE or OLDLINE. |
| MASK ‘mask’ | The Report Generator is to apply the specified mask pattern to the value of the associated item. Masking rules vary for alphanumeric, numeric, and date values. |
| NEWLINE [n] | Before displaying the associated item, the Report Generator is to skip n lines. The default value for n is 1. NEWLINE cannot be used in conjunction with LINE or OLDLINE. NEWLINE 1 is automatic for the first item in each heading or detail line command. (Use OLDLINE when overstriking is required.) |
| NEWPAGE [n] | Before displaying the associated item, the Report Generator is to skip to the nth page following the current page. The default value for n is 1. |
| NOPRINT | The Report Generator is to omit the display of the associated report item. (This option is useful for using a special expression format to initialize a variable, but not print the variable’s value, for example.) |
| OLDLINE | Before displaying the associated item, the Report Generator is to return to the start of the current line (“overstrike”). OLDLINE cannot be used in conjunction with NEWLINE or LINE. |
| SPACES n | Before displaying the associated item, the Report Generator is to move n character columns to the right. Zero (0) is a valid value for n. SPACES cannot be used in conjunction with COLUMN. |
| SPAN | The Report Generator is to display the associated item over one or more lines in a column WIDTH characters wide. When one line is full, display continues on the next line regardless of where the split occurs. |
| SUPPRESS | The Report Generator is to omit display of the associated item if its value has not changed since it was last displayed. |
| UNDERLINE | The Report Generator is to underline the associated item. |
| WIDTH n | The Report Generator is to use n as the output width for the associated item. (Normally, the output width is identical to the defined width of the item or the width of the mask or heading for the item, whichever is greatest. If n is less than the defined width of the item, the value is truncated unless WRAP or SPAN is also specified. |
| WRAP | The Report Generator is to display the associated item over one or more lines in a column WIDTH characters wide. An attempt is made to split the item at logical break points (e.g., a blank, a hyphen, an oblique (slash), a comma). |
Output Masks
Output masks are employed to format the output of fields, form fields, and data values in output operations.
The MASK format option in Zim Reports specifies an output mask pattern for a report item.
The $mask function specifies an output masking pattern to be applied to fields, form fields, and data values and returns a character string with the result of the masking operation.
The Field Mask attribute defines the expected output format of a field’s data value when it is printed or listed in Zim Reports, or by the list or output commands.
Mask patterns used with any of the three options described above are constructed in the same manner using the same set of available characters.
However, the set of characters available varies according to the data type of the item being masked. For more information on mask patterns and their relation to data types, see Masking.
Selected Examples of Mask Patterns for Numbers
In the following examples, leading or trailing spaces are indicated by / in the Output column.
Output of Sign Placeholders
| Sign Placeholder | Output When Masked Value <0 | Output When masked Value >=0 |
|---|---|---|
| ‘-‘ | – | / |
| ‘+’ | – | + |
| ‘CR’ | CR | // |
| ‘DB’ | DB | // |
| ‘)’ | ) | / |
| ‘(‘ | ( | / |
Behaviour of Fixed Text Characters
| Output Mask Pattern | Item Value | Output |
|---|---|---|
| ‘ZZ/ZZZZ’ | 1234 | ///1234 |
| ‘ZZ/ZZZZ’ | 12345 | /1/2345 |
| ‘Z9/ZZZZ’ | 1234 | /0/1234 |
| ‘***,***’ | 999 | ****999 |
Behaviour of Float Characters
| Output Mask Pattern | Item Value | Output |
|---|---|---|
| ‘$$$,$$9.99CR’ | 1324.77 | /$1,324.77// |
| ‘$$$,$$9.99CR’ | -56.88 | ////$56.88CR |
| ‘$$,$$9.99DB’ | -2566.44 | $2,566.44DB |
| ‘$$,$$9.99DB’ | .00 | /////$.00// |
| ‘$,$$9.99+’ | 1324.77 | 1,324.77+ |
| ‘$$$9.99+’ | -56.88 | /$56.88- |
| ‘(((9,999,99)’ | -1324.82 | //(1,324.82) |
| ‘((ZZ,999.99)’ | -386.41 | //( 386.41) |
| ‘$.$$’ | 0.00 | //// |
| ‘($$,$$9.99)’ | -56.88 | ///($56.88) |
| ‘($$,$$9.99)’ | -5.2 | ////($5.20) |
| ‘+$$,$$$.99’ | -56.88 | ///-$56.88 |
| ‘+$$,$$$.99’ | 2562.55 | +$2,562.55 |
Mask Patterns and the Language Customizer
Certain characters inserted into the output value by a mask are defined internally in the software.
The Language Customizer (ZIMLANG) administrative utility is used to redefine the internal characters and strings used by the software in a variety of circumstances, such as output masks.
For example, the currency placeholder $, is by default the dollar sign $. However, it can be redefined to output other symbols, such as the Euro sign €, the pound sign £, etc.
To achieve this, the Language Customizer can redefine the currency symbol output by the currency placeholder.
When using the Language Customizer to edit the software’s internal characters and strings, note the following:
- In application programs, output masks are always specified using the standard mask pattern characters. This rule applies to mask patterns specified in reports, in field and form field definitions, and in the $mask function.
- In user interface displays and output, the characters output by a mask pattern are determined by the software’s internal values.
For example, in Zim application programs, the dollar sign $ is universally used as the currency placeholder.
However, the currency symbol output by the placeholder depends on the current language customization (if any).
How to Use The Report Generator
The Report Generator takes a report specification and creates a report for viewing or printing.
The elements that must or can be provided to the Report Generator in the report specification are
- set of records
- page structure
- report headings and footings
- page headings and footings
- break headings and footings
- item position and format
How To Construct Report Specifications
A report specification is a series of commands that describe the set of data to be used in the report, the values to be extracted from the data set, and the formatting to be applied to each value and to the report in general.
The general form of a report specification is
REPORT FROM…
report commands
ENDREPORT
Reports can be line-oriented or column-oriented in their formatting.
How To Use Report Commands
Between REPORT FROM, that initiates the report and specifies the set of database records on which the report is to be based, and ENDREPORT, that marks the end of the report specification, any meaningful combination of the following commands can be used.
REPORT HEADING, REPORT FOOTING
Identifies and formats the data that is to appear at the very start and end of the report.
Always line-oriented by default, even in column-oriented reports. Can be column-oriented if desired.
PAGE HEADING, PAGE FOOTING
Identifies and formats the data that is to appear at the top and bottom of each page of the report.
Always line-oriented.
PAGE LEFT, PAGE RIGHT
In column-oriented reports, specifies “headings” that are to appear at the left-hand and right-hand sides of each page of the report.
DETAIL LINE
Extracts and formats values from the set of records specified in the REPORT FROM command, and manages the headings for each set of values.
Obeys the orientation specified in the REPORT FROM command.
BREAK
Specifies the conditions for dividing detail lines into groups and subgroups, and specifies the headings and footings that are to be output for each group.
The break headings and footings obey the orientation specified in the REPORT FROM command. In column-oriented reports, break headings and footings can be line-oriented if desired. Break headings and footings can differ in orientation.
COLUMN BREAK
In column-oriented reports, specifies the headings and footings that are to be output each time DETAIL LINE values carry over to a new tier of the report.
How To Specify the Report Set
The set specification is specified in the REPORT FROM command.
Only those records that fit the set specification are reported. One DETAIL LINE is produced for each record. The records are reported from top to bottom in sequential order. Typically, therefore, the set specification includes a SORT clause to place the records into a logical order.
Sorting is essential if breaks are to be included in the report. (As each record is processed, the break indicator is checked to determine whether a break has occurred.)
How To Specify Report Headings and Footings
Report headings are specified in the REPORT HEADING command; report footings, in the REPORT FOOTING command.
Report headings are processed before any records identified by the set specification are read.
The items specified in the report heading are output only once, at the start of the report.
Report footings are processed after all records identified by the set specification are read.
The items specified in the report footing are output only once, at the end of the report.
How To Specify Page Headings and Footings
Page headings and footings are specified in the PAGE HEADING, PAGE FOOTING, PAGE LEFT, and PAGE RIGHT commands.
Page headings and footings are processed when a page boundary is reached.
The items specified in the page headings/footings are output on every page of the report. The values can vary, however, depending on the source of the items (e.g., the current member from the set specification) and their format (e.g., NOPRINT, SUPPRESS).
How To Specify Breaks and Break Headings and Footings
Breaks, with their associated headings and footings are specified in the BREAK (Reports) command.
Breaks are processed when the break indicator expression changes in value. Many break levels can be specified in one report. Break headings and footings are processed when a break occurs at the corresponding level.
The items specified in the break heading are output when the first record of the set specification is processed, and when the first record of each new break group is processed. The values can vary, however, depending on the source of the items (e.g., the current member from the set specification) and their format (e.g., NOPRINT, SUPPRESS).
The items specified in the break footing are output when the last record of each break group is processed, and when the last record of the set specification is processed. The values can vary, however, depending on the source of the items (e.g., the current member from the set specification) and their format (e.g., NOPRINT, SUPPRESS).
How To Specify Item Position and Format
The items output by the various report commands can be explicitly specified, drawn from the records identified in the set specification, or produced by the evaluation of an expression that involves groups of such values, plus operators and functions, as desired.
Each item is individually positioned and formatted using report format options.
Other formatting of items can be accomplished using character functions such as $trim and $concat.
How To Specify the Report Page Structure
The general structure of a report page is specified in the REPORT FROM command.
Structural details that can be controlled include the overall width and depth of the page, the four margins (top, bottom, left, and right), the spacing between subsequent items on the same line, and the orientation of the entire report (line-oriented or column-oriented).
Available Format Options
Report format options describe where and how each report item is to be displayed and printed. Format options define the appearance of the report, its contents, and the position and appearance of its data, headings, and footings. Each data item in the report can be followed by any meaningful group of format options (See Conventions). Each group of format options begins and ends with a colon. Within the colons, each format options is separated from the next by at least one space.
Some format options are designed for text reports while other for graphical reports, sometimes both.
The following is the Report Format Options description for graphical reports, where “n” can be any positive integer:
| ITEM | Description |
| FIELD ‘template field’ | Associates this report item to a template field and inherits all existing formats in this template field like font, size, color, etc. |
| NEWPAGE [n] | Before displaying this item, skip to the nth page following the current page. The default value for n is 1. |
| LINE n | Before displaying this item, skip to line n on the current page. N must be greater than the current line number. LINE cannot be used in conjunction with NEWLINE. |
| CENTER | Center this report item within the current PAGEWIDTH. The default for PAGEWIDTH is 80 characters. |
| NOPRINT | Suppress the display of the associated report item. For example, if you want to initialize some variables for use later in the report, you can use a command such as REPORT HEADING 9let TotSal=0) :noprint: to set the value of the variable TotSal without actually printing the value in the report. |
| WRAP | Wrap this report item onto one or more lines, in a column WIDTH positions wide. An attempt is made to split the line item at a logical point (e.g.: a blank, hyphen, slash, comma). WRAP is useful for printing long fields of text. |
| SPAN | Wrap this report item onto one or more lines, in a column WIDTH positions wide (similar to WRAP). Unlike WRAP, SPAN does not attempt to break the report item at logical points. |
| SUPPRESS | Suppress printing of this report item if its value has not changed since the last time it was displayed. |
| UNDERLINE | Underline this report item. |
| MASK ‘mask’ | Provides a pattern, or ‘mask’, that precisely defines how data is to be displayed. The output result depends both on the mask string and on the data value. Character, number and date masking rules differ (See How to Use Data Masks). |
The following is the Report Format Options description for text reports, where “n” can be any positive integer:
| ITEM | Description |
| NEWPAGE [n] | Before displaying this item, skip to the nth page following the current page. The default value for n is 1. |
| NEWLINE [n] | Before displaying this item, skip n lines. The default for n is 1. NEWLINE cannot be used in conjunction with LINE or OLDLINE. |
| LINE n | Before displaying this item, skip to line n on the current page. N must be greater than the current line number. LINE cannot be used in conjunction with NEWLINE or OLDLINE. |
| OLDLINE | Overstrike the current line. OLDLINE cannot be used in conjunction with NEWLINE or LINE. |
| CENTER | Center this report item within the current PAGEWIDTH. The default for PAGEWIDTH is 80 characters. |
| COLUMN n | Print this report item in column n of the line. COLUMN cannot be used in conjunction with SPACES. |
| SPACES n | Before displaying this item, move n spaces to the right from the current position in the line (n can be zero). SPACES cannot be used in conjunction with COLUMN. |
| NOPRINT | Suppress the display of the associated report item. For example, if you want to initialize some variables for use later in the report, you can use a command such as REPORT HEADING 9let TotSal=0) :noprint: to set the value of the variable TotSal without actually printing the value in the report. |
| WIDTH n | Change the column width of this report item to n characters. The width of a report item is normally determined from the defined width of the item or the item’s heading. WIDTH lets you shrink or expand the item’s width. If n is less than the defined width of the report item, the data value is truncated, unless you also use WRAP or SPAN. |
| WRAP | Wrap this report item onto one or more lines, in a column WIDTH positions wide. An attempt is made to split the line item at a logical point (e.g.: a blank, hyphen, slash, comma). WRAP is useful for printing long fields of text. |
| SPAN | Wrap this report item onto one or more lines, in a column WIDTH positions wide (similar to WRAP). Unlike WRAP, SPAN does not attempt to break the report item at logical points. |
| SUPPRESS | Suppress printing of this report item if its value has not changed since the last time it was displayed. |
| UNDERLINE | Underline this report item. |
| HEADING ‘text’ | Supplies a heading for the associated report item. If HEADING is not specified, the field headings are used when displaying fields from entity sets, relationships, documents, and forms; variable names when displaying variables; and spaces in all other cases. You can turn all headings off by specifying COLUMN HEADING OFF in a DETAIL LINE command. |
| MASK ‘mask’ | Provides a pattern, or ‘mask’, that precisely defines how data is to be displayed. The output result depends both on the mask string and on the data value. Character, number and date masking rules differ (See How to Use Data Masks). |
Format options can be used in any report command except REPORT FROM and ENDREPORT.
Using Report Format Options
General points to remember when specifying format options for a report item are the following:
- The first report item in a command always begins on a new line (i.e.: NEWLINE 1 is automatic) in a line-oriented report. Also, this report item begins in column 1, unless otherwise specified.
- All line and column positioning is processed before the report item itself is formatted.
DETAIL LINE
Specifies the fields that are selected for a report
Syntax
DETAIL LINE [colheadings] [GRAPHIC [TEMPLATE name]] reportitem [:format:] [WHERE clause]
Parameters
| colheadings | Can be COLUMN HEADING OFF Specifies that column break headings are not to be re-displayed at the top of each report page. LEVEL n [WIDTH n ] LEVEL 0 causes level 0 column break headings to be printed at the top of each report page. This is the default break level. LEVEL n causes column break headings to be printed for each break level n or higher in the hierarchy (n must be an integer greater than or equal to 0). WIDTH n sets the width (in characters) of the space allotted to the column break heading. |
| TEMPLATE name | For graphical reports, the name of an optional template to define the layout of the report. |
| reportitem | Any value expression. If the expression is complex, it must be enclosed in parentheses. |
| format | A set of instructions defining the format for the associated reportitem. Format is enclosed in : (colons) and can consist of any valid combination of format options. |
Comments
The DETAIL LINE command is executed for every record of the set specified in the REPORT FROM command.
The column headings for all reportitems specified in the DETAIL LINE command are displayed, subject to any colheadings specification.
Only one detail line is produced for each record of the report set. If more than one DETAIL LINE command is used in a report specification, the DETAIL LINE command that is executed for a particular record in the report set is the first DETAIL LINE without a WHERE clause, or the first DETAIL LINE whose WHERE clause is true for that record.
For more information on format, see Available Format Options.
English 
Portuguese