run report with name


The run report with name statement prepares a report to be printed. The report to print is specified at runtime.


run report with name report_name {with restriction boolexp}{sort by field_name{nocase}{descend}}{by key_name | by number expr} {legends [string_expr_list|array_index_list]}{destination screen_boolean, printer_boolean {, export_type, export_name}}{printer printer_settings}{in dictionary product_ID}


report_name – A string variable or expression containing the name of a predefined report.

with restriction boolexp Any restrictions you want to place upon the report, in addition to the restrictions defined in the report itself. Boolexp is a boolean expression used to define the restriction criteria. The restrictions can be based upon any fields in the report’s main table, or any tables related to the main table. If you include two or more restrictions, enclose each restriction in parentheses, and enclose the entire set of restrictions in parentheses as well. You can link the different restriction clauses using or, and or not.

Since the report to be run won’t be specified until runtime, the compiler will not be able to catch restriction errors, as it will not be able to verify whether fields used in the boolexp actually exist in the report’s tables. All table fields used in the restriction must be part of tables attached to the report. Also, be sure to fully qualify the field names used in this parameter. If you don’t, your script will compile but you will receive an R_tree error when the script runs.

sort by field_name Allows you to sort the report by the contents of any field in the report, where field_name is the name of the field the sort will be based upon. You can include multiple fields in the sort by clause by listing them in their order of precedence, separated by commas. Be sure to fully qualify each field name used in this parameter. The sorting specified using this parameter overrides sorting specified in the report definition.

Since the report to be run won’t be specified until runtime, the compiler will not be able to catch any sorting errors, as it will not be able to verify whether fields specified in this parameter are actually used in the report.

Two additional sorting options are available to ignore case or sort the report in descending order. These keywords can be applied to each field used in the sort by clause.

nocase – If included, the case of field values won’t affect sorting. If not included, lowercase text will come before uppercase text in the sorting process.

descend – If included, the report data will be sorted in descending order. If not included, the report data will be sorted in ascending order.

by key_name | by number expr Specifies which table key will be used to access the records in the report’s main table. You can identify the key to be used by its name (by key_name) or by its numeric order in the list of table keys (by number expr). If this parameter isn’t included, the key specified in the report definition will be used.

legends string_expr_list|array_index_list – Allows you to specify strings to be displayed in legend fields on the report. Separate the strings by commas in the string_expr_list. Legend fields typically display information about the range of data included on the report, or how the report is sorted. If there are two or more legend fields on the report, list the strings in the appropriate order: the first value will be displayed in the Legend [1] field on the report, and so on.

Legend field values can also be used as the array index for array fields in calculated fields. Use the array_index_list to specify the appropriate numbers to be used as the indexes for the array fields; the values will be converted to long integers in the calculated field expressions and used as the array indexes.

destination screen_boolean, printer_boolean {export_type, export_name} Allows you to send the report to the screen, the printer, an export file, or any combination of the three. If this parameter isn’t included, when this statement is executed at runtime, the user will have to select a destination from the Report Destination window.

Set screen_boolean to true to send the report output to the screen. Set printer_boolean to true to send the report output to the printer.

Use the export_type and export_name parameters to send the report output to an export file. The following provides a detailed explanation of each of these parameters:

export_type A constant that allows you to specify the format for a report sent to an export file. Use one of the following constants:





Text file


Tab-delimited file


Comma-delimited file


HTML file


XML file


Adobe PDF (Portable Document Format) file

If the data from the report will be appended to an existing text file, the APPENDFILE constant must be included with the export type constant; for instance, TEXTFILE+APPENDFILE indicates  that  the  report  will  be appended to an existing text file. The name of that text file should be defined in the export_name parameter.

You cannot export a report to a PDF file and print it to a printer at the same time.

export_name A text string containing the name and path (in generic format) that the export file will be saved with. If you don’t supply a path, Dexterity will save the file in the current directory.

printer printer_settings This clause specifies a particular printer to which this report should be printed. The printer_settings parameter should be set to the value of the text field that was returned by the Printer_Define() function when the printer was defined.

This clause is independent of the destination clause. If this clause is included but the destination clause isn’t, the Report Destination window will appear when this statement is executed at runtime. If the Printer option is marked in the Report Destination window, the printer specified in this clause will be the printer named in the Print dialog that appears when the Report Destination window is closed.

If both the destination clause and the printer clause are included in a run report with name statement, the destination clause takes precedence. For example, if the printer_boolean parameter is set to false, the report will not be sent to a printer, even if the printer clause is used.

in dictionary product_ID – A clause containing the integer product ID for a third-party dictionary from which you want a report run.


You may not always be able to use the with restriction and sort by clauses, since you won’t know which report is going to be run. However, these clauses can be useful if you have a limited set of reports that could be run using the run report with name statement, and they all have common tables and fields upon which you can set restrictions or sorting options.

Documentation Feedback