LABEL Command
Sends labels from a label file (lbx) to the specified output.
The LABEL command can interpret Visual FoxPro report files (.frx format) as well as label files. You can also use LABEL to run character-based label files created in FoxPro for MS-DOS.
LABEL [FORM FileName1 | FORM ?] [ENVIRONMENT] [Scope]
[FOR lExpression1] [WHILE lExpression2] [NOOPTIMIZE]
[RANGE nStartPage [, nEndPage]]
[NOCONSOLE | OFF ] [SAMPLE] [PDSETUP]
[NAME ObjectName]
[OBJECT oReportListener | TYPE iExpression]
[TO PRINTER [PROMPT] | TO FILE FileName2]
[PREVIEW [PreviewDestination] [NOWAIT] [WINDOW WindowName]]
Parameters
[FORM FileName1 | FORM ?]
Specifies the name of the label file or displays the Open dialog box so you can select an existing label file. The default file name extension for labels is .lbx.Note
If the label file is on a drive or volume other than the default or in a directory other than the current directory, you must also specify the drive and directory.
Calling LABEL without arguments opens the Open dialog box.
[ENVIRONMENT]
Included for backward compatibility with 2.x labels. For more information, see Controlling Data in Reports.Tip
You can restore the data environment associated with a Visual FoxPro label by setting the data environment's AutoOpenTables property to True (.T.). To make sure that the label environment closes when the label finishes printing, set the AutoCloseTables property to True (.T.). For more information, see AutoOpenTables Property and AutoCloseTables Property.
[Scope]
Specifies a range of records. Includes only the records that fall within the range. The scope clauses are: ALL, NEXT <nRecords>, RECORD <nRecordNumber>, and REST. The default scope for LABEL is ALL records.Note
When you include a Scope clause, the scope operates only on the table in the active work area.
For more information on scope clauses, see Scope Clauses.
[FOR lExpression1]
Specifies a condition whereby only the records that satisfy the logical condition lExpression1 are included. This argument allows you to filter out records you do not want to include.Rushmore Query Optimization optimizes a query created with LABEL ... FOR if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause.
For more information, see SET OPTIMIZE Command and Using Rushmore Query Optimization to Speed Data Access.
[WHILE lExpression2]
Specifies a condition where records are included while the logical expression lExpression2 evaluates to True (.T.).[NOOPTIMIZE]
Disables Rushmore Query Optimization of LABEL.For more information, see SET OPTIMIZE Command and Using Rushmore Query Optimization to Speed Data Access.
[RANGE nStartPage [, nEndPage]]
Specifies a range of pages to print or other output.The nStartPage parameter specifies the first page to print, while the nEndPage parameter specifies the last page to print. If nEndPage is omitted, the last page to print defaults to 32,767.
RANGE selects pages for output, while scope clauses, FOR, and WHILE clauses select records. These selection criteria do not have an effect if you choose to print from preview, unless you have specified object-assisted mode by using the OBJECT clause or SET REPORTBEHAVIOR 90. In object-assisted mode, you can print either the full RANGE you specified on the original LABEL command or some subset of that page range, using the ReportListener.CommandClauses's PrintPageCurrent, PrintRangeFrom, and PrintRangeTo members. For more information, see OnPreviewClose Method.
[NOCONSOLE | OFF]
Suppresses displaying labels in the main Visual FoxPro window or a user-defined window when printing labels or sending them to a file.When you use Visual FoxPro 9.0's object-assisted output mode, LABEL does not display the contents of your label to the current output window, so the NOCONSOLE and OFF keywords have no effect on native behavior. However, the keywords are available in the ReportListener.CommandClauses object. You can evaluate them in your ReportListener derived classes, and opt to suppress a display of label content or other user feedback based on their contents. For more information, see CommandClauses Property.
[SAMPLE]
If you use character-based labels created in FoxPro for MS-DOS, SAMPLE can be used to test label alignment. The record pointer does not move during SAMPLE alignment tests If you use the SAMPLE keyword, the prompt Do you want more samples? appears after a sample label prints. Choose Yes to retest your label alignment.SAMPLE is ignored for graphics-based labels created in Visual FoxPro.
[PDSETUP]
Loads a printer driver setup.You can include PDSETUP to use a printer driver setup for printing character-based labels created in FoxPro for MS-DOS. PDSETUP is ignored when you print graphics-based labels created in Visual FoxPro.
[NAME ObjectName]
Specifies an object variable name for the data environment of a label. The data environment and the objects in the data environment have properties and methods, for example AddObject, that need to be set or called at run time. The object variable provides access to these properties and methods. If you omit the NAME clause, Visual FoxPro uses as a default the name of the label file that can be referenced in the code associated with the events.[OBJECT oReportListener | TYPE iExpression ]
Invokes Visual FoxPro's object-assisted output mode. Use either an object reference to an object derived from the ReportListener base class, or a numeric value specifying a type of output. For more information, see ReportListener Object, ListenerType Property, and OutputType Property (Visual FoxPro).The OBJECT clause on an individual LABEL command takes precedence over the current setting of SET REPORTBEHAVIOR.
[TO PRINTER [PROMPT] | TO [FILE] FileName2 [[ADDITIVE] ASCII]
Sends the label file to the printer or sends labels to a text file specified with FileName2 with the default file name extension of .txt.The PROMPT keyword displays the Print dialog box before printing starts. In object-assisted mode, the options enabled in the Print dialog box are affected by the ReportListener.CommandClauses.PrintPageCurrent member value.
When you omit the ASCII keyword or use Visual FoxPro's object-assisted output mode writes PostScript or other printer codes to the text file along with the content of your label layout. To create an ASCII text file from the label definition file, SET REPORTBEHAVIOR 80 and include the ASCII keyword.
Note
When you include the ASCII keyword, you can process labels on a computer that has no printer driver setups installed. Without the ASCII keyword, a LABEL command issued on a computer that has no printer driver setups installed generates an error.
An ASCII file contains only text. Any font or color settings, graphics, lines, rectangles, or rounded rectangles in the label definition file do not appear in the ASCII text file.
To append new content to an ASCII file instead of overwriting it, precede the ASCII keyword with the ADDITIVE keyword. The ADDITIVE and ASCII keywords must be specified in the order shown.
Omitting the ASCII keyword or using Visual FoxPro's object-assisted output mode writes PostScript or other printer codes to the text file.
[PREVIEW [PreviewDestination] [NOWAIT] [WINDOW WindowName]]
Displays the labels in a preview window instead of printing the labels. By default, the preview window is modal but provides access to the Print Preview toolbar. The NOWAIT keyword specifies that Visual FoxPro does not wait at run time for the preview window to close before continuing program execution.Tip
Character-based reports and labels created in FoxPro MS-DOS have a special character-based preview window. This mechanism is not affected by SET REPORTBEHAVIOR and does not support the OBJECT clause or WINDOW-related clauses.
If you include WINDOW <WindowName>, the preview window assumes the characteristics of the window, such as title, size, and so on, you specify with WindowName. WindowName can be the name property of a form object, or it can be a variable referencing a window created with DEFINE WINDOW. For more information, see DEFINE WINDOW Command.
The following table describes possible values for PreviewDestination. You can use the WINDOW clause alone or in combination with either PreviewDestination.
PreviewDestination
Description
[IN WINDOW WindowName]
Specifies a window for previewing a label layout.
If you include IN WINDOW <WindowName>, the label is previewed in the window you specify with WindowName.
IN SCREEN
Specifies that the preview displays in the main Visual FoxPro window and cannot be moved outside it.
Remarks
You can create label files using the CREATE LABEL Command or MODIFY LABEL Command.
When you use Visual FoxPro's object-assisted output mode, all the clauses of the LABEL FORM command are available to your ReportListener in its CommandClauses member object, with the exception of record selection clauses (scope, FOR, and WHILE). You can use the CommandClauses.RecordTotal attribute for information about the scope of the label run, or assign these values to your ReportListener object before running your labels. The CommandClauses Property topic gives you more information about how each clause is represented in the CommandClauses member object.