SYS(1037) - Page Setup Dialog Box
Displays the Visual FoxPro default or report Page Setup dialog box, or sets printer settings for the default printer in Visual FoxPro or for the report printer environment.
SYS(1037 [, nValue])
Parameters
nValue
Specifies a value that determines the functionality of SYS(1037).The following table lists the possible values of nValue.
nValue
Description
0 or omitted
Opens the default Page Setup dialog box.
1
Opens the report Page Setup dialog box.
2
Sets a report's printer environment settings to the default printer settings.
3
Sets the default printer settings to a report's printer environment settings.
Note
When nValue is set to a value of 1, 2, or 3, the report table or cursor must be opened exclusively.
Return Value
Character. SYS(1037) returns "1" if Visual FoxPro takes any action affecting aspects of the printer environment or printer settings; otherwise, it returns "0".
Note
In some cases, if the user pressed OK in the dialog box without making any explicit selection, it may not be obvious what changes occurred. However, Visual FoxPro has examined any aspects of the default printer environment or the printer settings in a report file and refreshed anything in these settings that do not match the full list of attributes available from the information provided by the Page Setup dialog box. Since this action occurs, the function returns "1."
Remarks
SYS(1037) displays the Page Setup dialog box so you can change printer settings such as the paper size and orientation. The settings available in the Page Setup dialog box depend on the printer installed. SYS(1037) also sets the printer environment settings for the report to the default printer settings or the default printer settings to the report printer environment settings. For more information, see Page Setup Dialog Box (Visual FoxPro).
SYS(1037,<N>) and Reports
SYS(1037,1), SYS(1037,2), and SYS(1037,3) are primarily useful for developers working with Visual FoxPro 9.0 Report System extension features. For more information about these features, see Extending Report Functionality in Visual FoxPro.
All three report-related SYS(1037,<N>) variants require access to a cursor or open table with the same format as a report (.frx) or label (.lbx) definition file. The report must be selected as a cursor or opened as a table before you call the function, and Visual FoxPro requires the report table to be opened exclusively. Otherwise, an error occurs when you call the function. For more information about the structure of report and label tables, see Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx).
SYS(1037,1) provides a way for developers implementing Report Builder extensions to invoke the native page setup dialog box and persist the user's choices directly to a report or label table. For more information, see Extending Reports at Design Time.
Saving the current printer environment
SYS(1037,2) serves as a way to save current printer settings to a cursor temporarily so you can restore the printer environment later. As such, this function always stores complete details to the cursor you provide. If this cursor is a real report, and did not have a printer environment saved to it before you used SYS(1037,2), it has a complete printer environment saved to it afterwards. If you do not want printer environment details to remain in this cursor, it is your responsibility to clear out the relevant fields later. To avoid the need to perform this cleanup task, simply provide a temporary cursor in the correct format with one record in it, rather than using a real report or label with SYS(1037,2). For more information, see How to: Save the Printer Environment for Reports.
SYS(1037,2) preserves any information already in the report's printer environment settings. It adds settings that are not currently in the report's printer environment, and does not overwrite existing settings.
For example, if a report definition includes ORIENTATION=1 and COPIES=3, to specify a landscape report and three printed copies, the default printer environment will not overwrite this setting with a portrait orientation. However, if you remove the line specifying COPIES=3 from the report definition before calling the function, the report definition will include a COPIES=<N> line after calling the function. This line will match the current Visual FoxPro default.
Because this behavior is additive, if you want to save the full default Visual FoxPro default printer environment, you should use an empty cursor with this function, or make sure the relevant fields are completely empty before calling SYS(1037,2).
Restoring the current printer environment
SYS(1037,3) restores printer settings from a report definition to the current Visual FoxPro default. Although it may seem counter-intuitive, using this variant of the function requires complete printer environment information in the report or label, and therefore may write data to the cursor as well as changing the default printer environment. If your report or label did not have complete information before you used the function, it will have complete information after you use it.
Respecting user-override of printer settings
In previous versions of Visual FoxPro, saving printer settings in reports used three fields in the table's first record: the EXPR, TAG, and TAG2 fields. In Visual FoxPro 9.0, if you choose not to save Printer Environment with a report, much less information is stored in these fields, making it possible for your report to work more appropriately with a wider variety of printers.
In Visual FoxPro 9.0, when you design reports, you can also override any settings stored in these fields by using a fourth field, PICTURE, in first record. Your stored settings in PICTURE override any settings for the same printer attributes in the EXPR and TAG fields. Note that these settings are case-sensitive.
SYS(1037) is aware of user settings in PICTURE and takes them into account when restoring printer environment from a report or label file.
When you run reports or labels, users may have yet another level of override of stored printer settings: the PROMPT clause on REPORT FORM and LABEL commands. If you use this keyword, or if you provide equivalent instructions with a ReportListener object's CommandClauses.Prompt member, any settings provided by the user at runtime take precedence over settings stored in the report as well as default Visual FoxPro printer environment settings. For more information, see REPORT FORM Command, LABEL Command, and CommandClauses Property.
See Also
Concepts
Understanding and Extending Report Structure