CommandClauses Property

Article
07/09/2007

Provides a list of the options specified for a REPORT FORM or LABEL command.

ReportListener.CommandClauses

Return Value

An object of Empty class, during or after the execution of a REPORT FORM or LABEL command.

The default value when you first create an instance of the ReportListener object is null (.NULL.)

Remarks

Applies To: ReportListener Object.

The Report Engine provides a CommandClauses object to the ReportListener during a report run, so the ReportListener can take action based on any options you specified on the command. This object is similar to the CommandClauses object that the Report Designer provides to the Report Builder Application during a design session. See Understanding Report Builder Events for more information.

Not every member of the CommandClauses object for ReportListeners exactly matches a REPORT FORM command keyword, and not all members are available for the same period of time. For example, the RecordTotal member is provided as a convenience to ReportListeners by the Engine when the Engine evaluates the REPORT FORM scope. This evaluation occurs between the LoadReport and BeforeReport event, so you cannot use RecordTotal during LoadReport.

Tip

You can use the ReportListener Debug Foundation Class to compare the CommandClauses members during the LoadReport and BeforeReport events.

The following table lists the CommandClauses members and discusses their contents and availability. Unless otherwise specified, the member and correct value is available from LoadReport through UnloadReport during a report run. Also, unless otherwise specified, neither the Report Engine nor the ReportListener base class uses these values; they are provided for the use of code in classes derived from ReportListener.

Note

All references to REPORT FORM commands should be understood as referring equally to LABEL commands, unless explicitly mentioned.

CommandClauses member	Remarks
.ASCII	Logical value, indicates whether the ASCII keyword appeared on the REPORT FORM command. ASCII is not supported by the ReportListener baseclass, and the keyword is ignored by default. However, your derived class can choose to take action based on this keyword.
.DE_NAME	Character data value, represents the NAME clause of the REPORT FORM command. Although the value of .DE_NAME is correct from LoadReport on, the DataEnvironment reference is not available until BeforeReport. This value is always present, providing the name of the object reference to the report's DataEnvironment, whether or not you specified NAME on the command. As with DO FORM, Visual FoxPro provides a default public variable with the same name as the report or label file when you do not specify NAME.
.ENVIRONMENT	Logical value, indicates whether the ENVIRONMENT keyword appeared on the REPORT FORM command. This keyword is not often used on Visual FoxPro report runs; it is allowed for backward compatibility. You can use the reference specified in .DE_NAME to check the AutoOpenTables property of the DataEnvironment, instead.
.FILE	Character data type value, provides the fully-pathed name of the report or label file (frx or lbx).
.HEADING	Character data type, providing the contents of the HEADING text if you use the HEADING <cText>clause on the REPORT FORM command.
.INSCREEN	Logical value, indicates whether the REPORT FORM command included the IN SCREEN clause.
.INWINDOW	Character data type, provides the name of the window if you used the IN WINDOW <cText> on the REPORT FORM command. This value is an empty string if you do not use the IN WINDOW clause.
.ISDESIGNERLOADED	Logical value, indicates whether the REPORT FORM command was invoked during a Report Designer or Label Designer session.
.ISDESIGNERPROTECTED	Logical value, indicates whether the REPORT FORM command was invoked with the PROTECTED keyword during a Report Designer or Label Designer session.
.ISREPORT	Logical value, indicates whether the command was REPORT FORM`(.T.`) or LABEL (`.F.`).
.NOCONSOLE	Logical value, indicates whether the NOCONSOLE keyword appeared on the REPORT FORM command. NOCONSOLE is not directly supported by the ReportListener baseclass, because the object-assisted output is not echoed to the current Visual FoxPro output window. However, your derived class can choose to take action based on this keyword. For example, you could draw the output to an output window, or provide a text version of the report contents, during the report run, but omit this action when the command included NOCONSOLE.
.NODIALOG	Logical value, indicates whether the NODIALOG keyword appeared on the REPORT FORM command. The ReportListener baseclass supports NODIALOG by temporarily adjusting its QuietMode property value for the duration of the report run. See QuietMode Property for more information.
.NOEJECT	Logical value, indicates whether the NOEJECT keyword appeared on the REPORT FORM command.
.NOPAGEEJECT	Logical value, indicates whether the NOPAGEEJECT keyword appeared on the REPORT FORM command. The ReportListener baseclass provides more functionality than non-object-assisted Visual FoxPro reporting when you use NOPAGEEJECT. This property provides the ability to chain reports when you set the ReportListener's ListenerType property to the value `1` (preview). You can use it to chain reports in other report results you create. The ReportListener Base Foundation Class topic provides an example of two report runs being added to a single XML output document, using the NOPAGEJECT keyword.
.NORESET	Logical value, indicates whether the NORESET keyword appeared on the REPORT FORM command.
.NOWAIT	Logical value, indicates whether the NOWAIT keyword appeared on the REPORT FORM command. The ReportListener base class uses this value to evaluate how to call the Show method of the Preview Container. See The Preview Container API for more information.
.OFF	Logical value, indicates whether the OFF keyword appeared on the REPORT FORM command. This keyword was not previously documented for the REPORT FORM command. It serves the same function as NOCONSOLE in the ReportListener baseclass. Your derived classes can opt to treat it the same way as NOCONSOLE or differently.
.OUTPUTTO	Integer value, representing the various possibilities of the TO clause, which can be either TO PRINT or TO [FILE] <Filename>. If OUTPUTTO = `1`, the TO clause indicates that output goes to the printer. If OUTPUTTO = `2`, the TO clause indicates that output goes to a file. In the latter case, the CommandClauses.TOFILE member provides the filename. If there was no TO clause on the REPORT FORM command, this member has the value `0`. You can adjust the OUTPUTTO and TOFILE values dynamically in the LoadReport event or when choosing to print from preview, as described in the PROMPT entry below. Your changes to these values are respected when the ReportListener begins its print run.
.PDSETUP	Logical value, indicates whether the PDSETUP keyword appeared on the REPORT FORM command. As with other backward compatibility clauses on the REPORT FORM command, your derived classes are free to use this value for any purpose.
.PLAIN	Logical value, indicates whether the PLAIN keyword appeared on the REPORT FORM command.
.PREVIEW	Logical value, indicates whether the PREVIEW keyword appeared on the REPORT FORM command.
.PRINTPAGECURRENT	Integer value, defaults to `0`, provides a way for a PreviewContainer to give information to a ReportListener about what page was currently displayed when the PreviewContainer invoked the ReportListener's OnPreviewClose method. When the PreviewContainer uses OnPreviewClose's argument of `.T.` to request printing after preview, and if .PRINTPAGECURRENT is not `0`, the ReportListener can enable the "Current Page" feature in any dialog preceding printing, such as the native PROMPT dialog. See OnPreviewClose Method for more information.
.PRINTRANGEFROM, .PRINTRANGETO	Integer values, work together to indicate a subset of the output page range when printing after preview. .PRINTRANGEFROM defaults to `1` and .PRINTRANGETO defaults to `-1`. The maximum print range is always `1` to ReportListener.OutputPageCount. See OutputPageCount Property for more information.
.PROMPT	Logical value, indicates whether the PROMPT keyword appeared on the REPORT FORM command. The ReportDesigner adds a PROMPT clause when you choose to preview during a design session. Note You can adjust the .PROMPT member dynamically when previewing, for example in the OnPreviewClose(`.T.`) event. The `.T.` argument to OnPreviewClause indicates that you wish to Print when the preview ends. You can also change this value in the LoadReport event. Your change to the value is respected when the ReportListener begins its print run. You can chain multiple reports together, using NOPAGEEJECT, and the various reports may not all have had different values for CommandClauses.PROMPT. In this scenario, the only significant value for PROMPT the one on the last report in the chained set (the report without NOPAGEEJECT).
.RANGEFROM	Integer value, indicates the first argument to the RANGE clause when you use this clause on the REPORT FORM command. If you do not use the RANGE clause on your command, this member has the value `1`. The value can change between the LoadReport event and BeforeReport event, based on changed made by a user from a PROMPT dialog. RANGEFROM and RANGETO are evaluated by the base class ReportListener when you call the IncludePageInOutput Method.
.RANGETO	Integer value, indicates the second (optional) argument to the RANGE clause when you use this clause on the REPORT FORM command. If you do not use the RANGE clause on your command, or if you do not specify its second argument, this member has the value -`1`. The value can change between the LoadReport event and BeforeReport event, based on changed made by a user from a PROMPT dialog. RANGEFROM and RANGETO are evaluated by the base class ReportListener when you call the IncludePageInOutput Method.
.RECORDTOTAL	Integer value, indicates the full scope of records in the currently-selected alias that will be processed. Scope is based on the REPORT FORM command clauses and any other limiting conditions you may have set (such as a SET FILTER command). This value is `0` in LoadReport and contains the correct value beginning in BeforeReport. It is reset to `0` after UnloadReport.
.SAMPLE	Logical value, indicates whether the SAMPLE keyword appeared on the LABEL command. This keyword is not available for the REPORT FORM command. Therefore, this value is always `.F.` unless you use the LABEL command.
.STARTDATASESSION	Numeric value, indicates the data session in which you issued the REPORT FORM or LABEL command. For more information, see Understanding Visual FoxPro Object-Assisted Reporting.
.SUMMARY	Logical value, indicates whether the SUMMARY keyword appeared on the REPORT FORM command. This value is always `.F.` for a LABEL command; it is significant only to REPORT FORM commands.
.TOFILE	Character data type, indicates the target output filename when you use the TO [FILE] <Filename> clause on the REPORT FORM command. You can adjust this member dynamically, as discussed above under OUTPUTTO.
.TOFILEADDITIVE	Logical value, indicates whether the ADDITIVE keyword appeared on the REPORT FORM command as part of TO [FILE] <Filename> ASCII. This keyword applies only to ASCII and, as such, is ignored by the ReportListener baseclass.
.WINDOW	Character data type, provides the name of the window if you used the WINDOW <cText> on the REPORT FORM command. This value is an empty string if you do not use the WINDOW clause.

Example

The following example is taken from the ReportListener User Feedback Foundation Class. The UpdateListener class uses its CommandClauses.FILE member to determine an appropriate caption for its feedback window, in cases where the user has not specified a value for the PrintJobName property.

IF EMPTY(THIS.PrintJobName)
   cName = PROPER(JUSTFNAME(THIS.CommandClauses.FILE))
ELSE
   cName = THIS.PrintJobName
ENDIF   
THIS.ThermForm.Caption = ;
   cName + ": " + OUTPUTCLASS_CANCEL_INSTRUCTIONS_LOC

CommandClauses Property

Return Value

Remarks

Example

See Also

Reference

Other Resources

Additional resources