Running a report¶
run report |
Run a report |
SYNTAX
run report report_id [to filename | window_id | “PRINTER:printername[:filename][>docname]”] [ppf = param_file]
Runs the specified report. This command is used outside !report sections. If the report terminates with the end report command or naturally by reaching the end of the driving file, control returns to the statement following the run report. If the report terminates in any other way, the entire program terminates.
Changed in version 6.3.0.
It is now possible to specify the document name in the to parameter with the optional “>docname” syntax.
report_id |
The identifier of a report declared in the program by !report. |
|
The optional to clause defines a filename, window or file for a named printer to receive the report output |
[ppf = param_file] |
Defines the Printer parameter file to be used. |
Output¶
If the to clause is omitted and no printer parameter file specified, a temporary window for the report is created. The window has Next Page and Cancel Report options; on the last page, the Cancel Report option is replaced by an End option. This is an easy way to run a report to the screen.
Use the printer parameter file winrtf to create a rich text file, which will be viewed by the application configured to run files of this type (.rtf suffix). See below.
When printing to a window, the size of the window is adjusted automatically to fit the report and the page length is restricted to the screen height. The visible area of the screen window can be forced to a larger size by setting sys.PageLength and sys.PageWidth but Sculptor prevents the window size from exceeding the screen size.
Window: If the report is run to a window, and it runs to more than one page, a small control window with Next and Cancel image buttons is opened over the top left corner of the report window. This allows a report to be placed on the background of an existing window.
Filename: If the report is directed to a filename the file may be located on a remote server. This is indicated by a colon following the server name, so colons should not be used when running a report to a device name with a colon suffix, e.g. “PRN:”. The colon, which is not necessary, should be removed, or the device name will be taken to be a server. See Specifying a server in a pathname.
Windows print manager |
To print the report via the Windows Print Manager use one of the following special strings in the to clause of the run report command:
Spaces and case are irrelevant in these strings, so that, for example, “PrintManager” and “print manager”are equivalent. In both these cases a printer parameter file with Section 2, Entry 2 (Print manager) set to “W” must be used (such as winpm). Options for the Windows Print Manager dialog are set by assigning flags to the Sculptor system variable sys.PrintOptions. These options mostly have the effect of hiding, disabling or selecting controls in the dialog window.
|
Rich text print manager |
If the to filename clause is missing when a report is run with a type R printer parameter file, a temporary file is created and loaded automatically into the viewing program. The program waitdel.exe, which is supplied with Sculptor, is responsible for the deletion of this file. It waits for 30 seconds, ensuring that the the viewing application has had time to load the file, and then waits until it is able to delete it. A printer parameter file with Section 2, Entry 2 (Print manager) set to “R” must be used (such as winrtf). The viewing program is defined in Section 1, Entry 5 of the printer parameter file. Typical viewing programs include WordPad, NotePad and Word. |
File for named printer: The form to “PRINTER:printername:filename” outputs the report to the specified file without user dialog. This is equivalent to using Print Manager and checking the Print to file checkbox. The file is only suitable for the printer named in printername, and can be printed later using the MS-DOS type command:
type /b filename PRN
This feature is also useful for creating PDF format files, since it is possible to obtain print drivers that output in PDF format. When printing in PDF format, use the printer parameter file “winpm” or an equivalent Windows file. See Example 9 below. Not all PDF drivers work correctly unless a dialog is used, so a driver should always be tested to check that it supports printing to a file programmatically.
It is recommended that the forward slash character “/” is used in quoted pathnames. This works on MS-DOS/Windows, and avoids the need to use “\\”.
Note
When printing through the Windows Print Manager, the run report command sets the Document Name to the report_id. For normal printers the name chosen is not important but some PDF printers use the Document Name for the name of the created document.
New in version 6.3.0: See the new features.
In this case you can now change the Document Name using the following syntax:
run report myreport to "PRINTER:MyPDFPrinter>mydocument.pdf" ppf="winpm"
Printer parameter file¶
The optional ppf = clause defines the printer parameter file to be used. This defaults to the printer file that was specified in the command line. So if a report program were called as follows:
srepwc report4 deskjet
the printer parameter file deskjet is the default. Printer parameter files are stored in the directory $SCULPTOR/print.
If no printer file was specified in the command line, the ultimate default for a program run by srepwc is the file called printer. Therefore, to set a printer parameter file as the default, copy the compiled file (e.g. winpm.p) to printer.p.
If nph-srep, the version of srepwc with Internet compatibility is used, the ultimate default printer file is nullp.
Printer parameter files from a remote server can be used; specify the full path name of the file. See Example 7 below.
If the printer file name specified begins with a colon, and the environment variable $SCMASTER is defined, the file in $SCULPTOR/print is updated from the file in $SCMASTER/print, provided that the latter file exists and has a later timestamp. See Updating parameter files from a server and Example 8 below.
Printing to screen¶
New in version 6.3.3: See the new features.
A new built-in window has been added: winprinttoscreen
This window is the template for reports printed on the screen. If the program changes an attribute of this window, the changes affects all subsequent run report commands. However, some attributes are calculated by the run report command and some are not relevant to a report; changing these has no effect.
Because Sculptor reports are based on a character grid, all co-ordinates in this window must be specified in characters, regardless of whether the program specifies !chargrid ON or OFF.
Examples:
winprinttoscreen->xcreate = 4 /* default 0 */
winprinttoscreen->ycreate = 1 /* default 0 */
winprinttoscreen->view_width = 180 /* default 100 */
winprinttoscreen->view_height /* calculated from page length */
winprinttoscreen->palette = PAL_BLACK_WINDOW /* default WHITE */
Current defaults may change in the future. Reset an attribute to 0 to restore its default.
NOTES
The run report command does not return an exit status. If an operating system error occurs during the processing of the report, the program exits.
EXAMPLES
Run report to terminal
run report CodeList ppf = "pterm"
Direct the output to a file
run report CheckXref to "xreffile"
Direct the output to a window, using the default printer parameter file
run report Report3 to Window4
Use Windows Print Manager
run report TimeList to "printmanager" ppf = "winpm"
Create a rich text format file
run report Update to "update.rtf" ppf = "winrtf"
Direct output to a file on a remote server
run report RepList to "server:/usr/bill/replist.txt"
Use a printer parameter file on a remote server
run report Report3 to "PrintManager" ppf = "server2:/SCULPTOR/print/winpm"
Use a printer parameter file from the master Sculptor directory, updating locally
run report CDCheck to "PrintManager" ppf = ":winpm"
Output a report in PDF format to a named printer and file
run report rep_pdf to "PRINTER:BroadGun pdfMachine:c:/myapp/pdf" ppf="winpm"
Output a report in PDF format to a named printer and file using the document name (depends on the driver this has to be specified)
run report myreport to "PRINTER:MyPDFPrinter>mydocument.pdf" ppf="winpm"
RELATED TOPICS |